<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
    <title>7 The Web Layer 2.2.1</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <link rel="stylesheet" href="../css/main.css" type="text/css" media="screen, print" title="Style" charset="utf-8"/>
    <link rel="stylesheet" href="../css/pdf.css" type="text/css" media="print" title="PDF" charset="utf-8"/>
    <script type="text/javascript">
function addJsClass() {
    var classes = document.body.className.split(" ");
    classes.push("js");
    document.body.className = classes.join(" ");
}
    </script>
</head>

<body class="body" onload="addJsClass();">
<div id="navigation">
    <ul>
        <li>
            <div id="nav-summary" onmouseover="toggleNavSummary(false)" onmouseout="toggleNavSummary(true)">
                <a href="../guide/index.html" class="button">Table of contents</a>

                <div id="nav-summary-childs" style="display:none;">
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/introduction.html"><strong>1</strong><span>Introduction</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/gettingStarted.html"><strong>2</strong><span>Getting Started</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/upgradingFromPreviousVersionsOfGrails.html"><strong>3</strong><span>Upgrading from previous versions of Grails</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/conf.html"><strong>4</strong><span>Configuration</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/commandLine.html"><strong>5</strong><span>The Command Line</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/GORM.html"><strong>6</strong><span>Object Relational Mapping (GORM)</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/theWebLayer.html"><strong>7</strong><span>The Web Layer</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/validation.html"><strong>8</strong><span>Validation</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/services.html"><strong>9</strong><span>The Service Layer</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/testing.html"><strong>10</strong><span>Testing</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/i18n.html"><strong>11</strong><span>Internationalization</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/security.html"><strong>12</strong><span>Security</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/plugins.html"><strong>13</strong><span>Plugins</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/webServices.html"><strong>14</strong><span>Web Services</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/spring.html"><strong>15</strong><span>Grails and Spring</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/hibernate.html"><strong>16</strong><span>Grails and Hibernate</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/scaffolding.html"><strong>17</strong><span>Scaffolding</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/deployment.html"><strong>18</strong><span>Deployment</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0"><a href="../guide/contributing.html"><strong>19</strong><span>Contributing to Grails</span></a>
                    </div>
                    
                </div>
            </div>
        </li>
        <li class="separator selected">
            <a id="ref-button" onclick="localToggle(); return false;" href="#">Quick Reference</a>
        </li>
    </ul>
</div>
<div id="header">
    <div class="images clearfix">
        
        <span id="logo"><a href="http://grails.org" target="_blank"><img alt="Grails Logo" title="The Grails Framework" src="../img/grails.png" border="0"/></a></span>
        
        
        <span id="sponsor"><a href="http://springsource.com" target="_blank"><img alt="SpringSource Logo" title="SpringSource - Weapons for the War on Java Complexity" src="../img/springsource-logo.png" border="0"/></a></span>
        
    </div>
    <p>See the light - agile, industrial strength, rapid web application development made easy</p>
</div>


<table id="colset" border="0" cellpadding="0" cellspacing="0">
    <tr>
        <td id="col1">
            <div id="main" class="corner-all">

                
                    <div class="toc-item prev-left"><a href="../guide/GORM.html">&lt;&lt; <strong>6</strong><span>Object Relational Mapping (GORM)</span></a></div>
                

                <span id='toggle-col1' class="toggle">(<a href="#" onclick="localToggle(); return false;">Quick Reference</a>)</span>

                
                    <div class="toc-item next-right"><a href="../guide/validation.html"><strong>8</strong><span>Validation</span> >></a></div>
                


                <div class="project">
                    <h1>7 The Web Layer - Reference Documentation</h1>

                    <p><strong>Authors:</strong> Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith</p>

                    <p><strong>Version:</strong> 2.2.1</p>

                    
                </div>

                
                <div id="table-of-content">
                    <h2>Table of Contents</h2>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#controllers"><strong>7.1</strong><span>Controllers</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#understandingControllersAndActions"><strong>7.1.1</strong><span>Understanding Controllers and Actions</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#controllersAndScopes"><strong>7.1.2</strong><span>Controllers and Scopes</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#modelsAndViews"><strong>7.1.3</strong><span>Models and Views</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#redirectsAndChaining"><strong>7.1.4</strong><span>Redirects and Chaining</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#interceptors"><strong>7.1.5</strong><span>Controller Interceptors</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#dataBinding"><strong>7.1.6</strong><span>Data Binding</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#xmlAndJSON"><strong>7.1.7</strong><span>XML and JSON Responses</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#moreOnJSONBuilder"><strong>7.1.8</strong><span>More on JSONBuilder</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#uploadingFiles"><strong>7.1.9</strong><span>Uploading Files</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#commandObjects"><strong>7.1.10</strong><span>Command Objects</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#formtokens"><strong>7.1.11</strong><span>Handling Duplicate Form Submissions</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#typeConverters"><strong>7.1.12</strong><span>Simple Type Converters</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#asynchronousRequestProcessing"><strong>7.1.13</strong><span>Asynchronous Request Processing</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#gsp"><strong>7.2</strong><span>Groovy Server Pages</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#GSPBasics"><strong>7.2.1</strong><span>GSP Basics</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#variablesAndScopes"><strong>7.2.1.1</strong><span>Variables and Scopes</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#logicAndIteration"><strong>7.2.1.2</strong><span>Logic and Iteration</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#pageDirectives"><strong>7.2.1.3</strong><span>Page Directives</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#expressions"><strong>7.2.1.4</strong><span>Expressions</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#tags"><strong>7.2.2</strong><span>GSP Tags</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#tagVariablesAndScopes"><strong>7.2.2.1</strong><span>Variables and Scopes</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#tagLogicAndIteration"><strong>7.2.2.2</strong><span>Logic and Iteration</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#searchAndFiltering"><strong>7.2.2.3</strong><span>Search and Filtering</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#linksAndResources"><strong>7.2.2.4</strong><span>Links and Resources</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#formsAndFields"><strong>7.2.2.5</strong><span>Forms and Fields</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#tagsAsMethodCalls"><strong>7.2.2.6</strong><span>Tags as Method Calls</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#viewsAndTemplates"><strong>7.2.3</strong><span>Views and Templates</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#layouts"><strong>7.2.4</strong><span>Layouts with Sitemesh</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#resources"><strong>7.2.5</strong><span>Static Resources</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#includingResourcesUsingTheResourceTags"><strong>7.2.5.1</strong><span>Including resources using the resource tags</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#otherResourceTags"><strong>7.2.5.2</strong><span>Other resource tags</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#declaringResources"><strong>7.2.5.3</strong><span>Declaring resources</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#overridingPluginResources"><strong>7.2.5.4</strong><span>Overriding plugin resources</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#optimizingYourResources"><strong>7.2.5.5</strong><span>Optimizing your resources</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#debugging"><strong>7.2.5.6</strong><span>Debugging</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#preventingProcessingOfResources"><strong>7.2.5.7</strong><span>Preventing processing of resources</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#otherResourcesPlugins"><strong>7.2.5.8</strong><span>Other Resources-aware plugins</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#sitemeshContentBlocks"><strong>7.2.6</strong><span>Sitemesh Content Blocks</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#makingChangesToADeployedApplication"><strong>7.2.7</strong><span>Making Changes to a Deployed Application</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#GSPDebugging"><strong>7.2.8</strong><span>GSP Debugging</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#taglibs"><strong>7.3</strong><span>Tag Libraries</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#taglibVariablesAndScopes"><strong>7.3.1</strong><span>Variables and Scopes</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#simpleTags"><strong>7.3.2</strong><span>Simple Tags</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#logicalTags"><strong>7.3.3</strong><span>Logical Tags</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#iterativeTags"><strong>7.3.4</strong><span>Iterative Tags</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#namespaces"><strong>7.3.5</strong><span>Tag Namespaces</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#usingJSPTagLibraries"><strong>7.3.6</strong><span>Using JSP Tag Libraries</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#tagReturnValue"><strong>7.3.7</strong><span>Tag return value</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#urlmappings"><strong>7.4</strong><span>URL Mappings</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#mappingToControllersAndActions"><strong>7.4.1</strong><span>Mapping to Controllers and Actions</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#embeddedVariables"><strong>7.4.2</strong><span>Embedded Variables</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#mappingToViews"><strong>7.4.3</strong><span>Mapping to Views</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#mappingToResponseCodes"><strong>7.4.4</strong><span>Mapping to Response Codes</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#mappingHTTP"><strong>7.4.5</strong><span>Mapping to HTTP methods</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#mappingWildcards"><strong>7.4.6</strong><span>Mapping Wildcards</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#automaticLinkRewriting"><strong>7.4.7</strong><span>Automatic Link Re-Writing</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#applyingConstraints"><strong>7.4.8</strong><span>Applying Constraints</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#namedMappings"><strong>7.4.9</strong><span>Named URL Mappings</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#customizingUrlFormat"><strong>7.4.10</strong><span>Customizing URL Formats</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#namespacedControllers"><strong>7.4.11</strong><span>Namespaced Controllers</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#webflow"><strong>7.5</strong><span>Web Flow</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#startAndEndStates"><strong>7.5.1</strong><span>Start and End States</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#actionStatesAndViewStates"><strong>7.5.2</strong><span>Action States and View States</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#flowExecutionEvents"><strong>7.5.3</strong><span>Flow Execution Events</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#flowScopes"><strong>7.5.4</strong><span>Flow Scopes</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#dataBindingAndValidation"><strong>7.5.5</strong><span>Data Binding and Validation</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#subflowsAndConversations"><strong>7.5.6</strong><span>Subflows and Conversations</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#filters"><strong>7.6</strong><span>Filters</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#applyingFilters"><strong>7.6.1</strong><span>Applying Filters</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#filterTypes"><strong>7.6.2</strong><span>Filter Types</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#filterVariablesAndScopes"><strong>7.6.3</strong><span>Variables and Scopes</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#filterDependencies"><strong>7.6.4</strong><span>Filter Dependencies</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#ajax"><strong>7.7</strong><span>Ajax</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#ajaxSupport"><strong>7.7.1</strong><span>Ajax Support</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#remotingLinking"><strong>7.7.1.1</strong><span>Remoting Linking</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#updatingContent"><strong>7.7.1.2</strong><span>Updating Content</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#remoteFormSubmission"><strong>7.7.1.3</strong><span>Remote Form Submission</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:20px"><a href="#ajaxEvents"><strong>7.7.1.4</strong><span>Ajax Events</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#ajaxWithPrototype"><strong>7.7.2</strong><span>Ajax with Prototype</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#ajaxWithDojo"><strong>7.7.3</strong><span>Ajax with Dojo</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#ajaxWithGWT"><strong>7.7.4</strong><span>Ajax with GWT</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:10px"><a href="#ajaxOnTheServer"><strong>7.7.5</strong><span>Ajax on the Server</span></a>
                    </div>
                    
                    <div class="toc-item" style="margin-left:0px"><a href="#contentNegotiation"><strong>7.8</strong><span>Content Negotiation</span></a>
                    </div>
                    
                </div>
                

                
<a name="6. The Web Layer"><!-- Legacy link --></a>
<h1 id="theWebLayer">7 The Web Layer</h1>


<a name="6.1 Controllers"><!-- Legacy link --></a>
<h2 id="controllers">7.1 Controllers</h2>
A controller handles requests and creates or prepares the response. A controller can generate the response directly or delegate to a view. To create a controller, simply create a class whose name ends with <code>Controller</code> in the <code>grails-app/controllers</code> directory (in a subdirectory if it's in a package).<p class="paragraph"/>The default <a href="../guide/single.html#urlmappings" class="guide">URL Mapping</a> configuration ensures that the first part of your controller name is mapped to a URI and each action defined within your controller maps to URIs within the controller name URI.


<a name="6.1.1 Understanding Controllers and Actions"><!-- Legacy link --></a>
<h2 id="understandingControllersAndActions">7.1.1 Understanding Controllers and Actions</h2>
<h4>Creating a controller</h4><p class="paragraph"/>Controllers can be created with the <a href="../ref/Command Line/create-controller.html" class="commandLine">create-controller</a> or <a href="../ref/Command Line/generate-controller.html" class="commandLine">generate-controller</a> command. For example try running the following command from the root of a Grails project:<p class="paragraph"/><div class="code"><pre>grails create&#45;controller book</pre></div><p class="paragraph"/>The command will create a controller at the location <code>grails-app/controllers/myapp/BookController.groovy</code>:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">package</span> myapp<p class="paragraph"/>class BookController &#123;<p class="paragraph"/>    def index() &#123; &#125;
&#125;</pre></div><p class="paragraph"/>where "myapp" will be the name of your application, the default package name if one isn't specified.<p class="paragraph"/><code>BookController</code> by default maps to the /book URI (relative to your application root).<p class="paragraph"/><blockquote class="note">
The <code>create-controller</code> and <code>generate-controller</code> commands are just for convenience and you can just as easily create controllers using your favorite text editor or IDE
</blockquote><p class="paragraph"/><h4>Creating Actions</h4><p class="paragraph"/>A controller can have multiple public action methods; each one maps to a URI:<p class="paragraph"/><div class="code"><pre>class BookController &#123;<p class="paragraph"/>    def list() &#123;<p class="paragraph"/>        // <span class="java&#45;keyword">do</span> controller logic
        // create model<p class="paragraph"/>        <span class="java&#45;keyword">return</span> model
    &#125;
&#125;</pre></div><p class="paragraph"/>This example maps to the <code>/book/list</code> URI by default thanks to the property being named <code>list</code>.<p class="paragraph"/><h4>Public Methods as Actions</h4><p class="paragraph"/>In earlier versions of Grails actions were implemented with Closures. This is still supported, but the preferred approach is to use methods.<p class="paragraph"/>Leveraging methods instead of Closure properties has some advantages:
<ul class="star">
<li>Memory efficient</li>
<li>Allow use of stateless controllers (<code>singleton</code> scope)</li>
<li>You can override actions from subclasses and call the overridden superclass method with <code>super.actionName()</code></li>
<li>Methods can be intercepted with standard proxying mechanisms, something that is complicated to do with Closures since they're fields.</li>
</ul><p class="paragraph"/>If you prefer the Closure syntax or have older controller classes created in earlier versions of Grails and still want the advantages of using methods, you can set the <code>grails.compile.artefacts.closures.convert</code> property to true in <code>BuildConfig.groovy</code>:
<div class="code"><pre>grails.compile.artefacts.closures.convert = <span class="java&#45;keyword">true</span></pre></div><p class="paragraph"/>and a compile-time AST transformation will convert your Closures to methods in the generated bytecode.<p class="paragraph"/><blockquote class="note">
If a controller class extends some other class which is not defined under the <code>grails-app/controllers/</code> directory, methods inherited from that class are not converted to controller actions.  If the intent is to expose those inherited methods as controller actions the methods may be overridden in the subclass and the subclass method may invoke the method in the super class.
</blockquote><p class="paragraph"/><h4>The Default Action</h4><p class="paragraph"/>A controller has the concept of a default URI that maps to the root URI of the controller, for example <code>/book</code> for <code>BookController</code>. The action that is called when the default URI is requested is dictated by the following rules:
<ul class="star">
<li>If there is only one action, it's the default</li>
<li>If you have an action named <code>index</code>, it's the default</li>
<li>Alternatively you can set it explicitly with the <code>defaultAction</code> property:</li>
</ul><p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> defaultAction = <span class="java&#45;quote">"list"</span></pre></div>


<a name="6.1.2 Controllers and Scopes"><!-- Legacy link --></a>
<h2 id="controllersAndScopes">7.1.2 Controllers and Scopes</h2>
<h4>Available Scopes</h4><p class="paragraph"/>Scopes are hash-like objects where you can store variables. The following scopes are available to controllers:
<ul class="star">
<li><a href="../ref/Controllers/servletContext.html" class="controllers">servletContext</a> - Also known as application scope, this scope lets you share state across the entire web application. The servletContext is an instance of <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/ServletContext.html" class="api">ServletContext</a></li>
<li><a href="../ref/Controllers/session.html" class="controllers">session</a> - The session allows associating state with a given user and typically uses cookies to associate a session with a client. The session object is an instance of <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpSession.html" class="api">HttpSession</a></li>
<li><a href="../ref/Controllers/request.html" class="controllers">request</a> - The request object allows the storage of objects for the current request only. The request object is an instance of <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletRequest.html" class="api">HttpServletRequest</a></li>
<li><a href="../ref/Controllers/params.html" class="controllers">params</a> - Mutable map of incoming request query string or POST parameters</li>
<li><a href="../ref/Controllers/flash.html" class="controllers">flash</a> - See below</li>
</ul><p class="paragraph"/><h4>Accessing Scopes</h4><p class="paragraph"/>Scopes can be accessed using the variable names above in combination with Groovy's array index operator, even on classes provided by the Servlet API such as the <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletRequest.html" class="api">HttpServletRequest</a>:<p class="paragraph"/><div class="code"><pre>class BookController &#123;
    def find() &#123;
        def findBy = params&#91;<span class="java&#45;quote">"findBy"</span>&#93;
        def appContext = request&#91;<span class="java&#45;quote">"foo"</span>&#93;
        def loggedUser = session&#91;<span class="java&#45;quote">"logged_user"</span>&#93;
    &#125;
&#125;</pre></div><p class="paragraph"/>You can also access values within scopes using the de-reference operator, making the syntax even more clear:<p class="paragraph"/><div class="code"><pre>class BookController &#123;
    def find() &#123;
        def findBy = params.findBy
        def appContext = request.foo
        def loggedUser = session.logged_user
    &#125;
&#125;</pre></div><p class="paragraph"/>This is one of the ways that Grails unifies access to the different scopes.<p class="paragraph"/><h4>Using Flash Scope</h4><p class="paragraph"/>Grails supports the concept of <a href="../ref/Controllers/flash.html" class="controllers">flash</a> scope as a temporary store to make attributes available for this request and the next request only. Afterwards the attributes are cleared. This is useful for setting a message directly before redirecting, for example:<p class="paragraph"/><div class="code"><pre>def delete() &#123;
    def b = Book.get(params.id)
    <span class="java&#45;keyword">if</span> (!b) &#123;
        flash.message = <span class="java&#45;quote">"User not found <span class="java&#45;keyword">for</span> id $&#123;params.id&#125;"</span>
        redirect(action:list)
    &#125;
    &#8230; // remaining code
&#125;</pre></div><p class="paragraph"/>When the <code>list</code> action is requested, the <code>message</code> value will be in scope and can be used to display an information message. It will be removed from the <code>flash</code> scope after this second request.<p class="paragraph"/>Note that the attribute name can be anything you want, and the values are often strings used to display messages, but can be any object type.<p class="paragraph"/><h4>Scoped Controllers</h4><p class="paragraph"/>By default, a new controller instance is created for each request. In fact, because the controller is <code>prototype</code> scoped, it is thread-safe since each request happens on its own thread.<p class="paragraph"/>You can change this behaviour by placing a controller in a particular scope. The supported scopes are:
<ul class="star">
<li><code>prototype</code> (default) - A new controller will be created for each request (recommended for actions as Closure properties)</li>
<li><code>session</code> - One controller is created for the scope of a user session</li>
<li><code>singleton</code> - Only one instance of the controller ever exists (recommended for actions as methods)</li>
</ul><p class="paragraph"/>To enable one of the scopes, add a static <code>scope</code> property to your class with one of the valid scope values listed above, for example<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> scope = <span class="java&#45;quote">"singleton"</span></pre></div><p class="paragraph"/>You can define the default strategy under in <code>Config.groovy</code> with the <code>grails.controllers.defaultScope</code> key, for example:<p class="paragraph"/><div class="code"><pre>grails.controllers.defaultScope = <span class="java&#45;quote">"singleton"</span></pre></div><p class="paragraph"/><blockquote class="note">
Use scoped controllers wisely. For instance, we don't recommend having any properties in a singleton-scoped controller since they will be shared for  <em class="italic">all</em>  requests. Setting a default scope other than <code>prototype</code> may also lead to unexpected behaviors if you have controllers provided by installed plugins that expect that the scope is <code>prototype</code>.
</blockquote>


<a name="6.1.3 Models and Views"><!-- Legacy link --></a>
<h2 id="modelsAndViews">7.1.3 Models and Views</h2>
<h4>Returning the Model</h4><p class="paragraph"/>A model is a Map that the view uses when rendering. The keys within that Map correspond to variable names accessible by the view. There are a couple of ways to return a model. First, you can explicitly return a Map instance:<p class="paragraph"/><div class="code"><pre>def show() &#123;
    &#91;book: Book.get(params.id)&#93;
&#125;</pre></div><p class="paragraph"/><blockquote class="note">
The above does  <em class="italic">not</em>  reflect what you should use with the scaffolding views - see the <a href="../guide/single.html#scaffolding" class="guide">scaffolding section</a> for more details.
</blockquote><p class="paragraph"/>If no explicit model is returned the controller's properties will be used as the model, thus allowing you to write code like this:<p class="paragraph"/><div class="code"><pre>class BookController &#123;<p class="paragraph"/>    List books
    List authors<p class="paragraph"/>    def list() &#123;
        books = Book.list()
        authors = Author.list()
    &#125;
&#125;</pre></div><p class="paragraph"/><blockquote class="note">
This is possible due to the fact that controllers are prototype scoped. In other words a new controller is created for each request. Otherwise code such as the above would not be thread-safe, and all users would share the same data.
</blockquote><p class="paragraph"/>In the above example the <code>books</code> and <code>authors</code> properties will be available in the view.<p class="paragraph"/>A more advanced approach is to return an instance of the Spring <a href="http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/web/servlet/ModelAndView.html" class="api">ModelAndView</a> class:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">import</span> org.springframework.web.servlet.ModelAndView<p class="paragraph"/>def index() &#123;
    // get some books just <span class="java&#45;keyword">for</span> the index page, perhaps your favorites
    def favoriteBooks = ...<p class="paragraph"/>    // forward to the list view to show them
    <span class="java&#45;keyword">return</span> <span class="java&#45;keyword">new</span> ModelAndView(<span class="java&#45;quote">"/book/list"</span>, &#91; bookList : favoriteBooks &#93;)
&#125;</pre></div><p class="paragraph"/>One thing to bear in mind is that certain variable names can not be used in your model:
<ul class="star">
<li><code>attributes</code></li>
<li><code>application</code></li>
</ul><p class="paragraph"/>Currently, no error will be reported if you do use them, but this will hopefully change in a future version of Grails.<p class="paragraph"/><h4>Selecting the View</h4><p class="paragraph"/>In both of the previous two examples there was no code that specified which <a href="../guide/single.html#gsp" class="guide">view</a> to render. So how does Grails know which one to pick? The answer lies in the conventions. Grails will look for a view at the location <code>grails-app/views/book/show.gsp</code> for this <code>list</code> action:<p class="paragraph"/><div class="code"><pre>class BookController &#123;
    def show() &#123;
         &#91;book: Book.get(params.id)&#93;
    &#125;
&#125;</pre></div><p class="paragraph"/>To render a different view, use the <a href="../ref/Controllers/render.html" class="controllers">render</a> method:<p class="paragraph"/><div class="code"><pre>def show() &#123;
    def map = &#91;book: Book.get(params.id)&#93;
    render(view: <span class="java&#45;quote">"display"</span>, model: map)
&#125;</pre></div><p class="paragraph"/>In this case Grails will attempt to render a view at the location <code>grails-app/views/book/display.gsp</code>. Notice that Grails automatically qualifies the view location with the <code>book</code> directory of the <code>grails-app/views</code> directory. This is convenient, but to access shared views you need instead you can use an absolute path instead of a relative one:<p class="paragraph"/><div class="code"><pre>def show() &#123;
    def map = &#91;book: Book.get(params.id)&#93;
    render(view: <span class="java&#45;quote">"/shared/display"</span>, model: map)
&#125;</pre></div><p class="paragraph"/>In this case Grails will attempt to render a view at the location <code>grails-app/views/shared/display.gsp</code>.<p class="paragraph"/>Grails also supports JSPs as views, so if a GSP isn't found in the expected location but a JSP is, it will be used instead.<p class="paragraph"/><h4>Rendering a Response</h4><p class="paragraph"/>Sometimes it's easier (for example with Ajax applications) to render snippets of text or code to the response directly from the controller. For this, the highly flexible <code>render</code> method can be used:<p class="paragraph"/><div class="code"><pre>render <span class="java&#45;quote">"Hello World!"</span></pre></div><p class="paragraph"/>The above code writes the text "Hello World!" to the response. Other examples include:<p class="paragraph"/><div class="code"><pre>// write some markup
render &#123;
   <span class="java&#45;keyword">for</span> (b in books) &#123;
      div(id: b.id, b.title)
   &#125;
&#125;</pre></div><p class="paragraph"/><div class="code"><pre>// render a specific view
render(view: 'show')</pre></div><p class="paragraph"/><div class="code"><pre>// render a template <span class="java&#45;keyword">for</span> each item in a collection
render(template: 'book_template', collection: Book.list())</pre></div><p class="paragraph"/><div class="code"><pre>// render some text with encoding and content type
render(text: <span class="java&#45;quote">"&#60;xml&#62;some xml&#60;/xml&#62;"</span>, contentType: <span class="java&#45;quote">"text/xml"</span>, encoding: <span class="java&#45;quote">"UTF&#45;8"</span>)</pre></div><p class="paragraph"/>If you plan on using Groovy's <code>MarkupBuilder</code> to generate HTML for use with the <code>render</code> method be careful of naming clashes between HTML elements and Grails tags, for example:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">import</span> groovy.xml.MarkupBuilder
&#8230;
def login() &#123;
    def writer = <span class="java&#45;keyword">new</span> StringWriter()
    def builder = <span class="java&#45;keyword">new</span> MarkupBuilder(writer)
    builder.html &#123;
        head &#123;
            title 'Log in'
        &#125;
        body &#123;
            h1 'Hello'
            form &#123;
            &#125;
        &#125;
    &#125;<p class="paragraph"/>    def html = writer.toString()
    render html
&#125;</pre></div><p class="paragraph"/>This will actually <a href="../guide/single.html#tagsAsMethodCalls" class="guide">call the form tag</a> (which will return some text that will be ignored by the <code>MarkupBuilder</code>). To correctly output a <code>&#60;form&#62;</code> element, use the following:<p class="paragraph"/><div class="code"><pre>def login() &#123;
    // &#8230;
    body &#123;
        h1 'Hello'
        builder.form &#123;
        &#125;
    &#125;
    // &#8230;
&#125;</pre></div>


<a name="6.1.4 Redirects and Chaining"><!-- Legacy link --></a>
<h2 id="redirectsAndChaining">7.1.4 Redirects and Chaining</h2>
<h4>Redirects</h4><p class="paragraph"/>Actions can be redirected using the <a href="../ref/Controllers/redirect.html" class="controllers">redirect</a> controller method:<p class="paragraph"/><div class="code"><pre>class OverviewController &#123;<p class="paragraph"/>    def login() &#123;&#125;<p class="paragraph"/>    def find() &#123;
        <span class="java&#45;keyword">if</span> (!session.user)
            redirect(action: 'login')
            <span class="java&#45;keyword">return</span>
        &#125;
        &#8230;
    &#125;
&#125;</pre></div><p class="paragraph"/>Internally the <a href="../ref/Controllers/redirect.html" class="controllers">redirect</a> method uses the <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletResponse.html" class="api">HttpServletResponse</a> object's <code>sendRedirect</code> method.<p class="paragraph"/>The <code>redirect</code> method expects one of:
<ul class="star">
<li>Another closure within the same controller class:</li>
</ul><p class="paragraph"/><div class="code"><pre>// Call the login action within the same class
redirect(action: login)</pre></div>
<ul class="star">
<li>The name of an action (and controller name if the redirect isn't to an action in the current controller):</li>
</ul><p class="paragraph"/><div class="code"><pre>// Also redirects to the index action in the home controller
redirect(controller: 'home', action: 'index')</pre></div>
<ul class="star">
<li> A URI for a resource relative the application context path:</li>
</ul><p class="paragraph"/><div class="code"><pre>// Redirect to an explicit URI
redirect(uri: <span class="java&#45;quote">"/login.html"</span>)</pre></div>
<ul class="star">
<li>Or a full URL:</li>
</ul><p class="paragraph"/><div class="code"><pre>// Redirect to a URL
redirect(url: <span class="java&#45;quote">"http://grails.org"</span>)</pre></div><p class="paragraph"/>Parameters can optionally be passed from one action to the next using the <code>params</code> argument of the method:<p class="paragraph"/><div class="code"><pre>redirect(action: 'myaction', params: &#91;myparam: <span class="java&#45;quote">"myvalue"</span>&#93;)</pre></div><p class="paragraph"/>These parameters are made available through the <a href="../ref/Controllers/params.html" class="controllers">params</a> dynamic property that accesses request parameters. If a parameter is specified with the same name as a request parameter, the request parameter is overridden and the controller parameter is used.<p class="paragraph"/>Since the <code>params</code> object is a Map, you can use it to pass the current request parameters from one action to the next:<p class="paragraph"/><div class="code"><pre>redirect(action: <span class="java&#45;quote">"next"</span>, params: params)</pre></div><p class="paragraph"/>Finally, you can also include a fragment in the target URI:<p class="paragraph"/><div class="code"><pre>redirect(controller: <span class="java&#45;quote">"test"</span>, action: <span class="java&#45;quote">"show"</span>, fragment: <span class="java&#45;quote">"profile"</span>)</pre></div><p class="paragraph"/>which will (depending on the URL mappings) redirect to something like "/myapp/test/show#profile".<p class="paragraph"/><h4>Chaining</h4><p class="paragraph"/>Actions can also be chained. Chaining allows the model to be retained from one action to the next. For example calling the <code>first</code> action in this action:<p class="paragraph"/><div class="code"><pre>class ExampleChainController &#123;<p class="paragraph"/>    def first() &#123;
        chain(action: second, model: &#91;one: 1&#93;)
    &#125;<p class="paragraph"/>    def second () &#123;
        chain(action: third, model: &#91;two: 2&#93;)
    &#125;<p class="paragraph"/>    def third() &#123;
        &#91;three: 3&#93;)
    &#125;
&#125;</pre></div><p class="paragraph"/>results in the model:<p class="paragraph"/><div class="code"><pre>&#91;one: 1, two: 2, three: 3&#93;</pre></div><p class="paragraph"/>The model can be accessed in subsequent controller actions in the chain using the <code>chainModel</code> map. This dynamic property only exists in actions following the call to the <code>chain</code> method:<p class="paragraph"/><div class="code"><pre>class ChainController &#123;<p class="paragraph"/>    def nextInChain() &#123;
        def model = chainModel.myModel
        &#8230;
    &#125;
&#125;</pre></div><p class="paragraph"/>Like the <code>redirect</code> method you can also pass parameters to the <code>chain</code> method:<p class="paragraph"/><div class="code"><pre>chain(action: <span class="java&#45;quote">"action1"</span>, model: &#91;one: 1&#93;, params: &#91;myparam: <span class="java&#45;quote">"param1"</span>&#93;)</pre></div>


<a name="6.1.5 Controller Interceptors"><!-- Legacy link --></a>
<h2 id="interceptors">7.1.5 Controller Interceptors</h2>
Often it is useful to intercept processing based on either request, session or application state. This can be achieved with action interceptors. There are currently two types of interceptors: before and after.<p class="paragraph"/><blockquote class="note">
If your interceptor is likely to apply to more than one controller, you are almost certainly better off writing a <a href="../guide/single.html#filters" class="guide">Filter</a>. Filters can be applied to multiple controllers or URIs without the need to change the logic of each controller
</blockquote><p class="paragraph"/><h4>Before Interception</h4><p class="paragraph"/>The <code>beforeInterceptor</code> intercepts processing before the action is executed. If it returns <code>false</code> then the intercepted action will not be executed. The interceptor can be defined for all actions in a controller as follows:<p class="paragraph"/><div class="code"><pre>def beforeInterceptor = &#123;
    println <span class="java&#45;quote">"Tracing action $&#123;actionUri&#125;"</span>
&#125;</pre></div><p class="paragraph"/>The above is declared inside the body of the controller definition.  It will be executed before all actions and does not interfere with processing. A common use case is very simplistic authentication:<p class="paragraph"/><div class="code"><pre>def beforeInterceptor = &#91;action: <span class="java&#45;keyword">this</span>.&#38;auth, except: 'login'&#93;<p class="paragraph"/>// defined with <span class="java&#45;keyword">private</span> scope, so it's not considered an action
<span class="java&#45;keyword">private</span> auth() &#123;
    <span class="java&#45;keyword">if</span> (!session.user) &#123;
        redirect(action: 'login')
        <span class="java&#45;keyword">return</span> <span class="java&#45;keyword">false</span>
    &#125;
&#125;<p class="paragraph"/>def login() &#123;
    // display login page
&#125;</pre></div><p class="paragraph"/>The above code defines a method called <code>auth</code>. A private method is used so that it is not exposed as an action to the outside world. The <code>beforeInterceptor</code> then defines an interceptor that is used on all actions  <em class="italic">except</em>  the login action and it executes the <code>auth</code> method. The <code>auth</code> method is referenced using Groovy's method pointer syntax. Within the method it detects whether there is a user in the session, and if not it redirects to the <code>login</code> action and returns <code>false</code>, causing the intercepted action to not be processed.<p class="paragraph"/><h4>After Interception</h4><p class="paragraph"/>Use the <code>afterInterceptor</code> property to define an interceptor that is executed after an action:<p class="paragraph"/><div class="code"><pre>def afterInterceptor = &#123; model &#45;&#62;
    println <span class="java&#45;quote">"Tracing action $&#123;actionUri&#125;"</span>
&#125;</pre></div><p class="paragraph"/>The after interceptor takes the resulting model as an argument and can hence manipulate the model or response.<p class="paragraph"/>An after interceptor may also modify the Spring MVC <a href="http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/web/servlet/ModelAndView.html" class="api">ModelAndView</a> object prior to rendering. In this case, the above example becomes:<p class="paragraph"/><div class="code"><pre>def afterInterceptor = &#123; model, modelAndView &#45;&#62;
    println <span class="java&#45;quote">"Current view is $&#123;modelAndView.viewName&#125;"</span>
    <span class="java&#45;keyword">if</span> (model.someVar) modelAndView.viewName = <span class="java&#45;quote">"/mycontroller/someotherview"</span>
    println <span class="java&#45;quote">"View is now $&#123;modelAndView.viewName&#125;"</span>
&#125;</pre></div><p class="paragraph"/>This allows the view to be changed based on the model returned by the current action. Note that the <code>modelAndView</code> may be <code>null</code> if the action being intercepted called <code>redirect</code> or <code>render</code>.<p class="paragraph"/><h4>Interception Conditions</h4><p class="paragraph"/>Rails users will be familiar with the authentication example and how the 'except' condition was used when executing the interceptor (interceptors are called 'filters' in Rails; this terminology conflicts with Servlet filter terminology in Java):<p class="paragraph"/><div class="code"><pre>def beforeInterceptor = &#91;action: <span class="java&#45;keyword">this</span>.&#38;auth, except: 'login'&#93;</pre></div><p class="paragraph"/>This executes the interceptor for all actions except the specified action. A list of actions can also be defined as follows:<p class="paragraph"/><div class="code"><pre>def beforeInterceptor = &#91;action: <span class="java&#45;keyword">this</span>.&#38;auth, except: &#91;'login', 'register'&#93;&#93;</pre></div><p class="paragraph"/>The other supported condition is 'only', this executes the interceptor for only the specified action(s):<p class="paragraph"/><div class="code"><pre>def beforeInterceptor = &#91;action: <span class="java&#45;keyword">this</span>.&#38;auth, only: &#91;'secure'&#93;&#93;</pre></div>


<a name="6.1.6 Data Binding"><!-- Legacy link --></a>
<h2 id="dataBinding">7.1.6 Data Binding</h2>
Data binding is the act of "binding" incoming request parameters onto the properties of an object or an entire graph of objects. Data binding should deal with all necessary type conversion since request parameters, which are typically delivered by a form submission, are always strings whilst the properties of a Groovy or Java object may well not be.<p class="paragraph"/>Grails uses <a href="http://www.springframework.org" target="blank">Spring</a>'s underlying data binding capability to perform data binding.<p class="paragraph"/><h4>Binding Request Data to the Model</h4><p class="paragraph"/>There are two ways to bind request parameters onto the properties of a domain class. The first involves using a domain classes' Map constructor:<p class="paragraph"/><div class="code"><pre>def save() &#123;
    def b = <span class="java&#45;keyword">new</span> Book(params)
    b.save()
&#125;</pre></div><p class="paragraph"/>The data binding happens within the code <code>new Book(params)</code>. By passing the <a href="../ref/Controllers/params.html" class="controllers">params</a> object to the domain class constructor Grails automatically recognizes that you are trying to bind from request parameters. So if we had an incoming request like:<p class="paragraph"/><div class="code"><pre>/book/save?title=The%20Stand&#38;author=Stephen%20King</pre></div><p class="paragraph"/>Then the <code>title</code> and <code>author</code> request parameters would automatically be set on the domain class. You can use the <a href="../ref/Domain Classes/properties.html" class="domainClasses">properties</a> property to perform data binding onto an existing instance:<p class="paragraph"/><div class="code"><pre>def save() &#123;
    def b = Book.get(params.id)
    b.properties = params
    b.save()
&#125;</pre></div><p class="paragraph"/>This has the same effect as using the implicit constructor.<p class="paragraph"/><blockquote class="warning">
These forms of data binding in Grails are very convenient, but also indiscriminate. In other words, they will bind  <em class="italic">all</em>  non-transient, typed instance properties of the target object, including ones that you may not want bound. Just because the form in your UI doesn't submit all the properties, an attacker can still send malign data via a raw HTTP request. Fortunately, Grails also makes it easy to protect against such attacks - see the section titled "Data Binding and Security concerns" for more information.
</blockquote><p class="paragraph"/><h4>Data binding and Single-ended Associations</h4><p class="paragraph"/>If you have a <code>one-to-one</code> or <code>many-to-one</code> association you can use Grails' data binding capability to update these relationships too. For example if you have an incoming request such as:<p class="paragraph"/><div class="code"><pre>/book/save?author.id=20</pre></div><p class="paragraph"/>Grails will automatically detect the <code>.id</code> suffix on the request parameter and look up the <code>Author</code> instance for the given id when doing data binding such as:<p class="paragraph"/><div class="code"><pre>def b = <span class="java&#45;keyword">new</span> Book(params)</pre></div><p class="paragraph"/>An association property can be set to <code>null</code> by passing the literal <code>String</code> "null". For example:<p class="paragraph"/><div class="code"><pre>/book/save?author.id=<span class="java&#45;keyword">null</span></pre></div><p class="paragraph"/><h4>Data Binding and Many-ended Associations</h4><p class="paragraph"/>If you have a one-to-many or many-to-many association there are different techniques for data binding depending of the association type.<p class="paragraph"/>If you have a <code>Set</code> based association (the default for a <code>hasMany</code>) then the simplest way to populate an association is to send a list of identifiers. For example consider the usage of <code>&#60;g:select&#62;</code> below:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:select name=<span class="xml&#45;quote">"books"</span>
          from=<span class="xml&#45;quote">"$&#123;Book.list()&#125;"</span>
          size=<span class="xml&#45;quote">"5"</span> multiple=<span class="xml&#45;quote">"yes"</span> optionKey=<span class="xml&#45;quote">"id"</span>
          value=<span class="xml&#45;quote">"$&#123;author?.books&#125;"</span> /&#62;</span></pre></div><p class="paragraph"/>This produces a select box that lets you select multiple values. In this case if you submit the form Grails will automatically use the identifiers from the select box to populate the <code>books</code> association.<p class="paragraph"/>However, if you have a scenario where you want to update the properties of the associated objects the this technique won't work. Instead you use the subscript operator:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:textField name=<span class="xml&#45;quote">"books&#91;0&#93;.title"</span> value=<span class="xml&#45;quote">"the Stand"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;g:textField name=<span class="xml&#45;quote">"books&#91;1&#93;.title"</span> value=<span class="xml&#45;quote">"the Shining"</span> /&#62;</span></pre></div><p class="paragraph"/>However, with <code>Set</code> based association it is critical that you render the mark-up in the same order that you plan to do the update in. This is because a <code>Set</code> has no concept of order, so although we're referring to <code>books0</code> and <code>books1</code> it is not guaranteed that the order of the association will be correct on the server side unless you apply some explicit sorting yourself.<p class="paragraph"/>This is not a problem if you use <code>List</code> based associations, since a <code>List</code> has a defined order and an index you can refer to. This is also true of <code>Map</code> based associations.<p class="paragraph"/>Note also that if the association you are binding to has a size of two and you refer to an element that is outside the size of association:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:textField name=<span class="xml&#45;quote">"books&#91;0&#93;.title"</span> value=<span class="xml&#45;quote">"the Stand"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;g:textField name=<span class="xml&#45;quote">"books&#91;1&#93;.title"</span> value=<span class="xml&#45;quote">"the Shining"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;g:textField name=<span class="xml&#45;quote">"books&#91;2&#93;.title"</span> value=<span class="xml&#45;quote">"Red Madder"</span> /&#62;</span></pre></div><p class="paragraph"/>Then Grails will automatically create a new instance for you at the defined position. If you "skipped" a few elements in the middle:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:textField name=<span class="xml&#45;quote">"books&#91;0&#93;.title"</span> value=<span class="xml&#45;quote">"the Stand"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;g:textField name=<span class="xml&#45;quote">"books&#91;1&#93;.title"</span> value=<span class="xml&#45;quote">"the Shining"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;g:textField name=<span class="xml&#45;quote">"books&#91;5&#93;.title"</span> value=<span class="xml&#45;quote">"Red Madder"</span> /&#62;</span></pre></div><p class="paragraph"/>Then Grails will automatically create instances in between. For example in the above case Grails will create 4 additional instances if the association being bound had a size of 2.<p class="paragraph"/>You can bind existing instances of the associated type to a <code>List</code> using the same <code>.id</code> syntax as you would use with a single-ended association. For example:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:select name=<span class="xml&#45;quote">"books&#91;0&#93;.id"</span> from=<span class="xml&#45;quote">"$&#123;bookList&#125;"</span>
          value=<span class="xml&#45;quote">"$&#123;author?.books&#91;0&#93;?.id&#125;"</span> /&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:select name=<span class="xml&#45;quote">"books&#91;1&#93;.id"</span> from=<span class="xml&#45;quote">"$&#123;bookList&#125;"</span>
          value=<span class="xml&#45;quote">"$&#123;author?.books&#91;1&#93;?.id&#125;"</span> /&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:select name=<span class="xml&#45;quote">"books&#91;2&#93;.id"</span> from=<span class="xml&#45;quote">"$&#123;bookList&#125;"</span>
          value=<span class="xml&#45;quote">"$&#123;author?.books&#91;2&#93;?.id&#125;"</span> /&#62;</span></pre></div><p class="paragraph"/>Would allow individual entries in the <code>books List</code> to be selected separately.<p class="paragraph"/>Entries at particular indexes can be removed in the same way too. For example:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:select name=<span class="xml&#45;quote">"books&#91;0&#93;.id"</span>
          from=<span class="xml&#45;quote">"$&#123;Book.list()&#125;"</span>
          value=<span class="xml&#45;quote">"$&#123;author?.books&#91;0&#93;?.id&#125;"</span>
          noSelection=<span class="xml&#45;quote">"&#91;'null': ''&#93;"</span>/&#62;</span></pre></div><p class="paragraph"/>Will render a select box that will remove the association at <code>books0</code> if the empty option is chosen.<p class="paragraph"/>Binding to a <code>Map</code> property works the same way except that the list index in the parameter name is replaced by the map key:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:select name=<span class="xml&#45;quote">"images&#91;cover&#93;.id"</span>
          from=<span class="xml&#45;quote">"$&#123;Image.list()&#125;"</span>
          value=<span class="xml&#45;quote">"$&#123;book?.images&#91;cover&#93;?.id&#125;"</span>
          noSelection=<span class="xml&#45;quote">"&#91;'null': ''&#93;"</span>/&#62;</span></pre></div><p class="paragraph"/>This would bind the selected image into the <code>Map</code> property <code>images</code> under a key of <code>"cover"</code>.<p class="paragraph"/><h4>Data binding with Multiple domain classes</h4><p class="paragraph"/>It is possible to bind data to multiple domain objects from the <a href="../ref/Controllers/params.html" class="controllers">params</a> object.<p class="paragraph"/>For example so you have an incoming request to:<p class="paragraph"/><div class="code"><pre>/book/save?book.title=The%20Stand&#38;author.name=Stephen%20King</pre></div><p class="paragraph"/>You'll notice the difference with the above request is that each parameter has a prefix such as <code>author.</code> or <code>book.</code> which is used to isolate which parameters belong to which type. Grails' <code>params</code> object is like a multi-dimensional hash and you can index into it to isolate only a subset of the parameters to bind.<p class="paragraph"/><div class="code"><pre>def b = <span class="java&#45;keyword">new</span> Book(params.book)</pre></div><p class="paragraph"/>Notice how we use the prefix before the first dot of the <code>book.title</code> parameter to isolate only parameters below this level to bind. We could do the same with an <code>Author</code> domain class:<p class="paragraph"/><div class="code"><pre>def a = <span class="java&#45;keyword">new</span> Author(params.author)</pre></div><p class="paragraph"/><h4>Data Binding and Action Arguments</h4><p class="paragraph"/>Controller action arguments are subject to request parameter data binding.  There are 2 categories of controller action arguments.  The first category is command objects.  Complex types are treated as command objects.  See the <a href="../guide/single.html#commandObjects" class="guide">Command Objects</a> section of the user guide for details.  The other category is basic object types.  Supported types are the 8 primitives, their corresponding type wrappers and <a href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/String.html" class="api">java.lang.String</a>.  The default behavior is to map request parameters to action arguments by name:<p class="paragraph"/><div class="code"><pre>class AccountingController &#123;<p class="paragraph"/>   // accountNumber will be initialized with the value of params.accountNumber
   // accountType will be initialized with params.accountType
   def displayInvoice(<span class="java&#45;object">String</span> accountNumber, <span class="java&#45;object">int</span> accountType) &#123;
       // &#8230;
   &#125;
&#125;</pre></div><p class="paragraph"/>For primitive arguments and arguments which are instances of any of the primitive type wrapper classes a type conversion has to be carried out before the request parameter value can be bound to the action argument.  The type conversion happens automatically.  In a case like the example shown above, the <code>params.accountType</code> request parameter has to be converted to an <code>int</code>.  If type conversion fails for any reason, the argument will have its default value per normal Java behavior (null for type wrapper references, false for booleans and zero for numbers) and a corresponding error will be added to the <code>errors</code> property of the defining controller.<p class="paragraph"/><div class="code"><pre>/accounting/displayInvoice?accountNumber=B59786&#38;accountType=bogusValue</pre></div><p class="paragraph"/>Since "bogusValue" cannot be converted to type int, the value of accountType will be zero, the controller's <code>errors.hasErrors()</code> will be true, the controller's <code>errors.errorCount</code> will be equal to 1 and the controller's <code>errors.getFieldError('accountType')</code> will contain the corresponding error.<p class="paragraph"/>If the argument name does not match the name of the request parameter then the <code>&#64;grails.web.RequestParameter</code> annotation may be applied to an argument to express the name of the request parameter which should be bound to that argument:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">import</span> grails.web.RequestParameter<p class="paragraph"/>class AccountingController &#123;<p class="paragraph"/>   // mainAccountNumber will be initialized with the value of params.accountNumber
   // accountType will be initialized with params.accountType
   def displayInvoice(@RequestParameter('accountNumber') <span class="java&#45;object">String</span> mainAccountNumber, <span class="java&#45;object">int</span> accountType) &#123;
       // &#8230;
   &#125;
&#125;</pre></div><p class="paragraph"/>
<h4>Data binding and type conversion errors</h4><p class="paragraph"/>Sometimes when performing data binding it is not possible to convert a particular String into a particular target type. This results in a type conversion error. Grails will retain type conversion errors inside the <a href="../ref/Domain Classes/errors.html" class="domainClasses">errors</a> property of a Grails domain class. For example:<p class="paragraph"/><div class="code"><pre>class Book &#123;
    &#8230;
    URL publisherURL
&#125;</pre></div><p class="paragraph"/>Here we have a domain class <code>Book</code> that uses the <code>java.net.URL</code> class to represent URLs. Given an incoming request such as:<p class="paragraph"/><div class="code"><pre>/book/save?publisherURL=a&#45;bad&#45;url</pre></div><p class="paragraph"/>it is not possible to bind the string <code>a-bad-url</code> to the <code>publisherURL</code> property as a type mismatch error occurs. You can check for these like this:<p class="paragraph"/><div class="code"><pre>def b = <span class="java&#45;keyword">new</span> Book(params)<p class="paragraph"/><span class="java&#45;keyword">if</span> (b.hasErrors()) &#123;
    println <span class="java&#45;quote">"The value $&#123;b.errors.getFieldError('publisherURL').rejectedValue&#125;"</span> +
            <span class="java&#45;quote">" is not a valid URL!"</span>
&#125;</pre></div><p class="paragraph"/>Although we have not yet covered error codes (for more information see the section on <a href="../guide/single.html#validation" class="guide">Validation</a>), for type conversion errors you would want a message from the <code>grails-app/i18n/messages.properties</code> file to use for the error. You can use a generic error message handler such as:<p class="paragraph"/><div class="code"><pre>typeMismatch.java.net.URL=The field &#123;0&#125; is not a valid URL</pre></div><p class="paragraph"/>Or a more specific one:<p class="paragraph"/><div class="code"><pre>typeMismatch.Book.publisherURL=The publisher URL you specified is not a valid URL</pre></div><p class="paragraph"/><h4>Data Binding and Security concerns</h4><p class="paragraph"/>When batch updating properties from request parameters you need to be careful not to allow clients to bind malicious data to domain classes and be persisted in the database. You can limit what properties are bound to a given domain class using the subscript operator:<p class="paragraph"/><div class="code"><pre>def p = Person.get(1)<p class="paragraph"/>p.properties&#91;'firstName','lastName'&#93; = params</pre></div><p class="paragraph"/>In this case only the <code>firstName</code> and <code>lastName</code> properties will be bound.<p class="paragraph"/>Another way to do this is is to use <a href="../guide/single.html#commandObjects" class="guide">Command Objects</a> as the target of data binding instead of domain classes. Alternatively there is also the flexible <a href="../ref/Controllers/bindData.html" class="controllers">bindData</a> method.<p class="paragraph"/>The <code>bindData</code> method allows the same data binding capability, but to arbitrary objects:<p class="paragraph"/><div class="code"><pre>def p = <span class="java&#45;keyword">new</span> Person()
bindData(p, params)</pre></div><p class="paragraph"/>The <code>bindData</code> method also lets you exclude certain parameters that you don't want updated:<p class="paragraph"/><div class="code"><pre>def p = <span class="java&#45;keyword">new</span> Person()
bindData(p, params, &#91;exclude: 'dateOfBirth'&#93;)</pre></div><p class="paragraph"/>Or include only certain properties:<p class="paragraph"/><div class="code"><pre>def p = <span class="java&#45;keyword">new</span> Person()
bindData(p, params, &#91;include: &#91;'firstName', 'lastName'&#93;&#93;)</pre></div><p class="paragraph"/><blockquote class="note">
Note that if an empty List is provided as a value for the <code>include</code> parameter then all fields will be subject to binding if they are not explicitly excluded.
</blockquote>



<h2 id="xmlAndJSON">7.1.7 XML and JSON Responses</h2>
<h4>Using the render method to output XML</h4><p class="paragraph"/>Grails supports a few different ways to produce XML and JSON responses. The first is the <a href="../ref/Controllers/render.html" class="controllers">render</a> method.<p class="paragraph"/>The <code>render</code> method can be passed a block of code to do mark-up building in XML:<p class="paragraph"/><div class="code"><pre>def list() &#123;<p class="paragraph"/>    def results = Book.list()<p class="paragraph"/>    render(contentType: <span class="java&#45;quote">"text/xml"</span>) &#123;
        books &#123;
            <span class="java&#45;keyword">for</span> (b in results) &#123;
                book(title: b.title)
            &#125;
        &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/>The result of this code would be something like:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;books&#62;</span>
    <span class="xml&#45;tag">&#60;book title=<span class="xml&#45;quote">"The Stand"</span> /&#62;</span>
    <span class="xml&#45;tag">&#60;book title=<span class="xml&#45;quote">"The Shining"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;/books&#62;</span></pre></div><p class="paragraph"/>Be careful to avoid naming conflicts when using mark-up building. For example this code would produce an error:<p class="paragraph"/><div class="code"><pre>def list() &#123;<p class="paragraph"/>    def books = Book.list()  // naming conflict here<p class="paragraph"/>    render(contentType: <span class="java&#45;quote">"text/xml"</span>) &#123;
        books &#123;
            <span class="java&#45;keyword">for</span> (b in results) &#123;
                book(title: b.title)
            &#125;
        &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/>This is because there is local variable <code>books</code> which Groovy attempts to invoke as a method.<p class="paragraph"/><h4>Using the render method to output JSON</h4><p class="paragraph"/>The <code>render</code> method can also be used to output JSON:<p class="paragraph"/><div class="code"><pre>def list() &#123;<p class="paragraph"/>    def results = Book.list()<p class="paragraph"/>    render(contentType: <span class="java&#45;quote">"text/json"</span>) &#123;
        books = array &#123;
            <span class="java&#45;keyword">for</span> (b in results) &#123;
                book title: b.title
            &#125;
        &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/>In this case the result would be something along the lines of:<p class="paragraph"/><div class="code"><pre>&#91;
    &#123;title:<span class="java&#45;quote">"The Stand"</span>&#125;,
    &#123;title:<span class="java&#45;quote">"The Shining"</span>&#125;
&#93;</pre></div><p class="paragraph"/>The same dangers with naming conflicts described above for XML also apply to JSON building.<p class="paragraph"/><h4>Automatic XML Marshalling</h4><p class="paragraph"/>Grails also supports automatic marshalling of <a href="../guide/single.html#GORM" class="guide">domain classes</a> to XML using special converters.<p class="paragraph"/>To start off with, import the <code>grails.converters</code> package into your controller:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">import</span> grails.converters.&#42;</pre></div><p class="paragraph"/>Now you can use the following highly readable syntax to automatically convert domain classes to XML:<p class="paragraph"/><div class="code"><pre>render Book.list() as XML</pre></div><p class="paragraph"/>The resulting output would look something like the following::<p class="paragraph"/><div class="code"><pre>&#60;?xml version=<span class="java&#45;quote">"1.0"</span> encoding=<span class="java&#45;quote">"ISO&#45;8859&#45;1"</span>?&#62;
&#60;list&#62;
  &#60;book id=<span class="java&#45;quote">"1"</span>&#62;
    &#60;author&#62;Stephen King&#60;/author&#62;
    &#60;title&#62;The Stand&#60;/title&#62;
  &#60;/book&#62;
  &#60;book id=<span class="java&#45;quote">"2"</span>&#62;
    &#60;author&#62;Stephen King&#60;/author&#62;
    &#60;title&#62;The Shining&#60;/title&#62;
  &#60;/book&#62;
&#60;/list&#62;</pre></div><p class="paragraph"/>An alternative to using the converters is to use the <a href="../guide/single.html#codecs" class="guide">codecs</a> feature of Grails. The codecs feature provides <a href="../guide/single.html#codecs" class="guide">encodeAsXML</a> and <a href="../guide/single.html#codecs" class="guide">encodeAsJSON</a> methods:<p class="paragraph"/><div class="code"><pre>def xml = Book.list().encodeAsXML()
render xml</pre></div><p class="paragraph"/>For more information on XML marshalling see the section on <a href="../guide/single.html#REST" class="guide">REST</a><p class="paragraph"/><h4>Automatic JSON Marshalling</h4><p class="paragraph"/>Grails also supports automatic marshalling to JSON using the same mechanism. Simply substitute <code>XML</code> with <code>JSON</code>:<p class="paragraph"/><div class="code"><pre>render Book.list() as JSON</pre></div><p class="paragraph"/>The resulting output would look something like the following:<p class="paragraph"/><div class="code"><pre>&#91;
    &#123;<span class="java&#45;quote">"id"</span>:1,
     <span class="java&#45;quote">"class"</span>:<span class="java&#45;quote">"Book"</span>,
     <span class="java&#45;quote">"author"</span>:<span class="java&#45;quote">"Stephen King"</span>,
     <span class="java&#45;quote">"title"</span>:<span class="java&#45;quote">"The Stand"</span>&#125;,
    &#123;<span class="java&#45;quote">"id"</span>:2,
     <span class="java&#45;quote">"class"</span>:<span class="java&#45;quote">"Book"</span>,
     <span class="java&#45;quote">"author"</span>:<span class="java&#45;quote">"Stephen King"</span>,
     <span class="java&#45;quote">"releaseDate"</span>:<span class="java&#45;keyword">new</span> Date(1194127343161),
     <span class="java&#45;quote">"title"</span>:<span class="java&#45;quote">"The Shining"</span>&#125;
 &#93;</pre></div><p class="paragraph"/>Again as an alternative you can use the <code>encodeAsJSON</code> to achieve the same effect.


<a name="6.1.8 More on JSONBuilder"><!-- Legacy link --></a>
<h2 id="moreOnJSONBuilder">7.1.8 More on JSONBuilder</h2>
The previous section on on XML and JSON responses covered simplistic examples of rendering XML and JSON responses. Whilst the XML builder used by Grails is the standard <a href="http://groovy.codehaus.org/Reading+XML+using+Groovy's+XmlSlurper" target="blank">XmlSlurper</a> found in Groovy, the JSON builder is a custom implementation specific to Grails.<p class="paragraph"/><h4>JSONBuilder and Grails versions</h4><p class="paragraph"/>JSONBuilder behaves different depending on the version of Grails you use. For version below 1.2 the deprecated <a href="../api/grails/web/JSONBuilder.html" class="api">grails.web.JSONBuilder</a> class is used. This section covers the usage of the Grails 1.2 JSONBuilder<p class="paragraph"/>For backwards compatibility the old <code>JSONBuilder</code> class is used with the <code>render</code> method for older applications; to use the newer/better <code>JSONBuilder</code> class set the following in <code>Config.groovy</code>:<p class="paragraph"/><div class="code"><pre>grails.json.legacy.builder = <span class="java&#45;keyword">false</span></pre></div><p class="paragraph"/><h4>Rendering Simple Objects</h4><p class="paragraph"/>To render a simple JSON object just set properties within the context of the Closure:<p class="paragraph"/><div class="code"><pre>render(contentType: <span class="java&#45;quote">"text/json"</span>) &#123;
    hello = <span class="java&#45;quote">"world"</span>
&#125;</pre></div><p class="paragraph"/>The above will produce the JSON:<p class="paragraph"/><div class="code"><pre>&#123;<span class="java&#45;quote">"hello"</span>:<span class="java&#45;quote">"world"</span>&#125;</pre></div><p class="paragraph"/><h4>Rendering JSON Arrays</h4><p class="paragraph"/>To render a list of objects simple assign a list:<p class="paragraph"/><div class="code"><pre>render(contentType: <span class="java&#45;quote">"text/json"</span>) &#123;
    categories = &#91;'a', 'b', 'c'&#93;
&#125;</pre></div><p class="paragraph"/>This will produce:<p class="paragraph"/><div class="code"><pre>&#123;<span class="java&#45;quote">"categories"</span>:&#91;<span class="java&#45;quote">"a"</span>,<span class="java&#45;quote">"b"</span>,<span class="java&#45;quote">"c"</span>&#93;&#125;</pre></div><p class="paragraph"/>You can also render lists of complex objects, for example:<p class="paragraph"/><div class="code"><pre>render(contentType: <span class="java&#45;quote">"text/json"</span>) &#123;
    categories = &#91; &#123; a = <span class="java&#45;quote">"A"</span> &#125;, &#123; b = <span class="java&#45;quote">"B"</span> &#125; &#93;
&#125;</pre></div><p class="paragraph"/>This will produce:<p class="paragraph"/><div class="code"><pre>&#123;<span class="java&#45;quote">"categories"</span>:&#91; &#123;<span class="java&#45;quote">"a"</span>:<span class="java&#45;quote">"A"</span>&#125; , &#123;<span class="java&#45;quote">"b"</span>:<span class="java&#45;quote">"B"</span>&#125;&#93; &#125;</pre></div><p class="paragraph"/>Use the special <code>element</code> method to return a list as the root:<p class="paragraph"/><div class="code"><pre>render(contentType: <span class="java&#45;quote">"text/json"</span>) &#123;
    element 1
    element 2
    element 3
&#125;</pre></div><p class="paragraph"/>The above code produces:<p class="paragraph"/><div class="code"><pre>&#91;1,2,3&#93;</pre></div><p class="paragraph"/><h4>Rendering Complex Objects</h4><p class="paragraph"/>Rendering complex objects can be done with Closures. For example:<p class="paragraph"/><div class="code"><pre>render(contentType: <span class="java&#45;quote">"text/json"</span>) &#123;
    categories = &#91;'a', 'b', 'c'&#93;
    title = <span class="java&#45;quote">"Hello JSON"</span>
    information = &#123;
        pages = 10
    &#125;
&#125;</pre></div><p class="paragraph"/>The above will produce the JSON:<p class="paragraph"/><div class="code"><pre>&#123;<span class="java&#45;quote">"categories"</span>:&#91;<span class="java&#45;quote">"a"</span>,<span class="java&#45;quote">"b"</span>,<span class="java&#45;quote">"c"</span>&#93;,<span class="java&#45;quote">"title"</span>:<span class="java&#45;quote">"Hello JSON"</span>,<span class="java&#45;quote">"information"</span>:&#123;<span class="java&#45;quote">"pages"</span>:10&#125;&#125;</pre></div><p class="paragraph"/><h4>Arrays of Complex Objects</h4><p class="paragraph"/>As mentioned previously you can nest complex objects within arrays using Closures:<p class="paragraph"/><div class="code"><pre>render(contentType: <span class="java&#45;quote">"text/json"</span>) &#123;
    categories = &#91; &#123; a = <span class="java&#45;quote">"A"</span> &#125;, &#123; b = <span class="java&#45;quote">"B"</span> &#125; &#93;
&#125;</pre></div><p class="paragraph"/>You can use the <code>array</code> method to build them up dynamically:<p class="paragraph"/><div class="code"><pre>def results = Book.list()
render(contentType: <span class="java&#45;quote">"text/json"</span>) &#123;
    books = array &#123;
        <span class="java&#45;keyword">for</span> (b in results) &#123;
            book title: b.title
        &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/><h4>Direct JSONBuilder API Access</h4><p class="paragraph"/>If you don't have access to the <code>render</code> method, but still want to produce JSON you can use the API directly:<p class="paragraph"/><div class="code"><pre>def builder = <span class="java&#45;keyword">new</span> JSONBuilder()<p class="paragraph"/>def result = builder.build &#123;
    categories = &#91;'a', 'b', 'c'&#93;
    title = <span class="java&#45;quote">"Hello JSON"</span>
    information = &#123;
        pages = 10
    &#125;
&#125;<p class="paragraph"/>// prints the JSON text
println result.toString()<p class="paragraph"/>def sw = <span class="java&#45;keyword">new</span> StringWriter()
result.render sw</pre></div>


<a name="6.1.9 Uploading Files"><!-- Legacy link --></a>
<h2 id="uploadingFiles">7.1.9 Uploading Files</h2>
<h4>Programmatic File Uploads</h4><p class="paragraph"/>Grails supports file uploads using Spring's <a href="http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/web/multipart/MultipartHttpServletRequest.html" class="api">MultipartHttpServletRequest</a> interface. The first step for file uploading is to create a multipart form like this:<p class="paragraph"/><div class="code"><pre>Upload Form: <span class="xml&#45;tag">&#60;br /&#62;</span>
    <span class="xml&#45;tag">&#60;g:uploadForm action=<span class="xml&#45;quote">"upload"</span>&#62;</span>
        <span class="xml&#45;tag">&#60;input type=<span class="xml&#45;quote">"file"</span> name=<span class="xml&#45;quote">"myFile"</span> /&#62;</span>
        <span class="xml&#45;tag">&#60;input type=<span class="xml&#45;quote">"submit"</span> /&#62;</span>
    <span class="xml&#45;tag">&#60;/g:uploadForm&#62;</span></pre></div><p class="paragraph"/>The <code>uploadForm</code> tag conveniently adds the <code>enctype="multipart/form-data"</code> attribute to the standard <code>&#60;g:form&#62;</code> tag.<p class="paragraph"/>There are then a number of ways to handle the file upload. One is to work with the Spring <a href="http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/web/multipart/MultipartFile.html" class="api">MultipartFile</a> instance directly:<p class="paragraph"/><div class="code"><pre>def upload() &#123;
    def f = request.getFile('myFile')
    <span class="java&#45;keyword">if</span> (f.empty) &#123;
        flash.message = 'file cannot be empty'
        render(view: 'uploadForm')
        <span class="java&#45;keyword">return</span>
    &#125;<p class="paragraph"/>    f.transferTo(<span class="java&#45;keyword">new</span> File('/some/local/dir/myfile.txt'))
    response.sendError(200, 'Done')
&#125;</pre></div><p class="paragraph"/>This is convenient for doing transfers to other destinations and manipulating the file directly as you can obtain an <code>InputStream</code> and so on with the <a href="http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/web/multipart/MultipartFile.html" class="api">MultipartFile</a> interface.<p class="paragraph"/><h4>File Uploads through Data Binding</h4><p class="paragraph"/>File uploads can also be performed using data binding. Consider this <code>Image</code> domain class:<p class="paragraph"/><div class="code"><pre>class Image &#123;
    <span class="java&#45;object">byte</span>&#91;&#93; myFile<p class="paragraph"/>    <span class="java&#45;keyword">static</span> constraints = &#123;
        // Limit upload file size to 2MB
        myFile maxSize: 1024 &#42; 1024 &#42; 2
    &#125;
&#125;</pre></div><p class="paragraph"/>If you create an image using the <code>params</code> object in the constructor as in the example below, Grails will automatically bind the file's contents as a <code>byte</code> to the <code>myFile</code> property:<p class="paragraph"/><div class="code"><pre>def img = <span class="java&#45;keyword">new</span> Image(params)</pre></div><p class="paragraph"/>It's important that you set the <a href="../ref/Constraints/size.html" class="constraints">size</a> or <a href="../ref/Constraints/maxSize.html" class="constraints">maxSize</a> constraints, otherwise your database may be created with a small column size that can't handle reasonably sized files. For example, both H2 and MySQL default to a blob size of 255 bytes for <code>byte</code> properties.<p class="paragraph"/>It is also possible to set the contents of the file as a string by changing the type of the <code>myFile</code> property on the image to a String type:<p class="paragraph"/><div class="code"><pre>class Image &#123;
   <span class="java&#45;object">String</span> myFile
&#125;</pre></div>


<a name="6.1.10 Command Objects"><!-- Legacy link --></a>
<h2 id="commandObjects">7.1.10 Command Objects</h2>
Grails controllers support the concept of command objects. A command object is a class that is used in conjunction with <a href="../guide/single.html#dataBinding" class="guide">data binding</a>, usually to allow validation of data that may not fit into an existing domain class.<p class="paragraph"/><blockquote class="note">
Note: A class is only considered to be a command object when it is used as a parameter of an action.
</blockquote><p class="paragraph"/><h4>Declaring Command Objects</h4><p class="paragraph"/>Command object classes are defined just like any other class.<p class="paragraph"/><div class="code"><pre>@grails.validation.Validateable
class LoginCommand &#123;
    <span class="java&#45;object">String</span> username
    <span class="java&#45;object">String</span> password<p class="paragraph"/>    <span class="java&#45;keyword">static</span> constraints = &#123;
        username(blank: <span class="java&#45;keyword">false</span>, minSize: 6)
        password(blank: <span class="java&#45;keyword">false</span>, minSize: 6)
    &#125;
&#125;</pre></div><p class="paragraph"/>In this example, the command object is marked with the <code>Validateable</code> annotation. The <code>Validateable</code> annotation allows the definition of <a href="../guide/single.html#constraints" class="guide">constraints</a> just like in <a href="../guide/single.html#GORM" class="guide">domain classes</a>. If the command object is defined in the same source file as the controller that is using it, Grails will automatically mark it as <code>Validateable</code>. It is not required that command object classes be validateable.<p class="paragraph"/><h4>Using Command Objects</h4><p class="paragraph"/>To use command objects, controller actions may optionally specify any number of command object parameters. The parameter types must be supplied so that Grails knows what objects to create and initialize.<p class="paragraph"/>Before the controller action is executed Grails will automatically create an instance of the command object class and populate its properties by binding the request parameters.  If the command object class is marked with <code>Validateable</code> then the command object will be validated. For example:<p class="paragraph"/><div class="code"><pre>class LoginController &#123;<p class="paragraph"/>    def login(LoginCommand cmd) &#123;
        <span class="java&#45;keyword">if</span> (cmd.hasErrors()) &#123;
            redirect(action: 'loginForm')
            <span class="java&#45;keyword">return</span>
        &#125;<p class="paragraph"/>        // work with the command object data
    &#125;
&#125;</pre></div><p class="paragraph"/><h4>Command Objects and Dependency Injection</h4><p class="paragraph"/>Command objects can participate in dependency injection. This is useful if your command object has some custom validation logic which uses a Grails <a href="../guide/single.html#services" class="guide">service</a>:<p class="paragraph"/><div class="code"><pre>@grails.validation.Validateable
class LoginCommand &#123;<p class="paragraph"/>    def loginService<p class="paragraph"/>    <span class="java&#45;object">String</span> username
    <span class="java&#45;object">String</span> password<p class="paragraph"/>    <span class="java&#45;keyword">static</span> constraints = &#123;
        username validator: &#123; val, obj &#45;&#62;
            obj.loginService.canLogin(obj.username, obj.password)
        &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/>In this example the command object interacts with the <code>loginService</code> bean which is injected by name from the Spring <code>ApplicationContext</code>.


<a name="6.1.11 Handling Duplicate Form Submissions"><!-- Legacy link --></a>
<h2 id="formtokens">7.1.11 Handling Duplicate Form Submissions</h2>
Grails has built-in support for handling duplicate form submissions using the "Synchronizer Token Pattern". To get started you define a token on the <a href="../ref/Tags/form.html" class="tags">form</a> tag:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:form useToken=<span class="xml&#45;quote">"true"</span> ...&#62;</span></pre></div><p class="paragraph"/>Then in your controller code you can use the <a href="../ref/Controllers/withForm.html" class="controllers">withForm</a> method to handle valid and invalid requests:<p class="paragraph"/><div class="code"><pre>withForm &#123;
   // good request
&#125;.invalidToken &#123;
   // bad request
&#125;</pre></div><p class="paragraph"/>If you only provide the <a href="../ref/Controllers/withForm.html" class="controllers">withForm</a> method and not the chained <code>invalidToken</code> method then by default Grails will store the invalid token in a <code>flash.invalidToken</code> variable and redirect the request back to the original page. This can then be checked in the view:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:if test=<span class="xml&#45;quote">"$&#123;flash.invalidToken&#125;"</span>&#62;</span>
  Don't click the button twice!
<span class="xml&#45;tag">&#60;/g:if&#62;</span></pre></div><p class="paragraph"/><blockquote class="warning">
The <a href="../ref/Controllers/withForm.html" class="controllers">withForm</a> tag makes use of the <a href="../ref/Controllers/session.html" class="controllers">session</a> and hence requires session affinity or clustered sessions if used in a cluster.
</blockquote>


<a name="6.1.12 Simple Type Converters"><!-- Legacy link --></a>
<h2 id="typeConverters">7.1.12 Simple Type Converters</h2>
<h3>Type Conversion Methods</h3><p class="paragraph"/>If you prefer to avoid the overhead of <a href="../guide/single.html#dataBinding" class="guide">Data Binding</a> and simply want to convert incoming parameters (typically Strings) into another more appropriate type the <a href="../ref/Controllers/params.html" class="controllers">params</a> object has a number of convenience methods for each type:<p class="paragraph"/><div class="code"><pre>def total = params.<span class="java&#45;object">int</span>('total')</pre></div><p class="paragraph"/>The above example uses the <code>int</code> method, and there are also methods for <code>boolean</code>, <code>long</code>, <code>char</code>, <code>short</code> and so on. Each of these methods is null-safe and safe from any parsing errors, so you don't have to perform any additional checks on the parameters.<p class="paragraph"/>Each of the conversion methods allows a default value to be passed as an optional second argument.  The default value will be returned if a corresponding entry cannot be found in the map or if an error occurs during the conversion.  Example:<p class="paragraph"/><div class="code"><pre>def total = params.<span class="java&#45;object">int</span>('total', 42)</pre></div><p class="paragraph"/>These same type conversion methods are also available on the <code>attrs</code> parameter of GSP tags.<p class="paragraph"/><h3>Handling Multi Parameters</h3><p class="paragraph"/>A common use case is dealing with multiple request parameters of the same name. For example you could get a query string such as <code>?name=Bob&#38;name=Judy</code>.<p class="paragraph"/>In this case dealing with one parameter and dealing with many has different semantics since Groovy's iteration mechanics for <code>String</code> iterate over each character. To avoid this problem the <a href="../ref/Controllers/params.html" class="controllers">params</a> object provides a <code>list</code> method that always returns a list:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">for</span> (name in params.list('name')) &#123;
    println name
&#125;</pre></div>


<a name="6.1.13 Asynchronous Request Processing"><!-- Legacy link --></a>
<h2 id="asynchronousRequestProcessing">7.1.13 Asynchronous Request Processing</h2>
Grails support asynchronous request processing as provided by the Servlet 3.0 specification. To enable the async features you need to set your servlet target version to 3.0 in BuildConfig.groovy:<p class="paragraph"/><div class="code"><pre>grails.servlet.version = <span class="java&#45;quote">"3.0"</span></pre></div><p class="paragraph"/>With that done ensure you do a clean re-compile as some async features are enabled at compile time.<p class="paragraph"/><blockquote class="note">
With a Servlet target version of 3.0 you can only deploy on Servlet 3.0 containers such as Tomcat 7 and above.
</blockquote><p class="paragraph"/><h4>Asynchronous Rendering</h4><p class="paragraph"/>You can render content (templates, binary data etc.) in an asynchronous manner by calling the <code>startAsync</code> method which returns an instance of the Servlet 3.0 <code>AsyncContext</code>. Once you have a reference to the <code>AsyncContext</code> you can use Grails' regular render method to render content:<p class="paragraph"/><div class="code"><pre>def index() &#123;
    def ctx = startAsync()
    ctx.start &#123;
        <span class="java&#45;keyword">new</span> Book(title:<span class="java&#45;quote">"The Stand"</span>).save()
        render template:<span class="java&#45;quote">"books"</span>, model:&#91;books:Book.list()&#93;
        ctx.complete()
    &#125;
&#125;</pre></div><p class="paragraph"/>Note that you must call the <code>complete()</code> method to terminate the connection.<p class="paragraph"/><h4>Resuming an Async Request</h4><p class="paragraph"/>You resume processing of an async request (for example to delegate to view rendering) by using the <code>dispatch</code> method of the <code>AsyncContext</code> class:<p class="paragraph"/><div class="code"><pre>def index() &#123;
    def ctx = startAsync()
    ctx.start &#123;
        // <span class="java&#45;keyword">do</span> working
        &#8230;
        // render view
        ctx.dispatch()
    &#125;
&#125;</pre></div>


<a name="6.2 Groovy Server Pages"><!-- Legacy link --></a>
<h2 id="gsp">7.2 Groovy Server Pages</h2>
Groovy Servers Pages (or GSP for short) is Grails' view technology. It is designed to be familiar for users of technologies such as ASP and JSP, but to be far more flexible and intuitive.<p class="paragraph"/>GSPs live in the <code>grails-app/views</code> directory and are typically rendered automatically (by convention) or with the <a href="../ref/Controllers/render.html" class="controllers">render</a> method such as:<p class="paragraph"/><div class="code"><pre>render(view: <span class="java&#45;quote">"index"</span>)</pre></div><p class="paragraph"/>A GSP is typically a mix of mark-up and GSP tags which aid in view rendering.<p class="paragraph"/><blockquote class="note">
Although it is possible to have Groovy logic embedded in your GSP and doing this will be covered in this document, the practice is strongly discouraged. Mixing mark-up and code is a <strong class="bold">bad</strong> thing and most GSP pages contain no code and needn't do so.
</blockquote><p class="paragraph"/>A GSP typically has a "model" which is a set of variables that are used for view rendering. The model is passed to the GSP view from a controller. For example consider the following controller action:<p class="paragraph"/><div class="code"><pre>def show() &#123;
    &#91;book: Book.get(params.id)&#93;
&#125;</pre></div><p class="paragraph"/>This action will look up a <code>Book</code> instance and create a model that contains a key called <code>book</code>. This key can then be referenced within the GSP view using the name <code>book</code>:<p class="paragraph"/><div class="code"><pre>$&#123;book.title&#125;</pre></div>


<a name="6.2.1 GSP Basics"><!-- Legacy link --></a>
<h2 id="GSPBasics">7.2.1 GSP Basics</h2>
In the next view sections we'll go through the basics of GSP and what is available to you. First off let's cover some basic syntax that users of JSP and ASP should be familiar with.<p class="paragraph"/>GSP supports the usage of <code>&#60;% %&#62;</code> scriptlet blocks to embed Groovy code (again this is discouraged):<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
     <span class="xml&#45;tag">&#60;% out &#60;&#60; <span class="xml&#45;quote">"Hello GSP!"</span> %&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>You can also use the <code>&#60;%= %&#62;</code> syntax to output values:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
     <span class="xml&#45;tag">&#60;%=<span class="xml&#45;quote">"Hello GSP!"</span> %&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>GSP also supports JSP-style server-side comments (which are not rendered in the HTML response) as the following example demonstrates:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
     <span class="xml&#45;tag">&#60;%&#45;&#45; This is my comment &#45;&#45;%&#62;</span>
     <span class="xml&#45;tag">&#60;%=<span class="xml&#45;quote">"Hello GSP!"</span> %&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div>


<a name="6.6.3 Variables and Scopes"><!-- Legacy link --></a>
<h2 id="variablesAndScopes">7.2.1.1 Variables and Scopes</h2>
Within the <code>&#60;% %&#62;</code> brackets you can declare variables:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;% now = new Date() %&#62;</span></pre></div><p class="paragraph"/>and then access those variables later in the page:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;%=now%&#62;</span></pre></div><p class="paragraph"/>Within the scope of a GSP there are a number of pre-defined variables, including:
<ul class="star">
<li><code>application</code> - The <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/ServletContext.html" class="api">javax.servlet.ServletContext</a> instance</li>
<li><code>applicationContext</code> The Spring <a href="http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/context/ApplicationContext.html" class="api">ApplicationContext</a> instance</li>
<li><code>flash</code> - The <a href="../ref/Controllers/flash.html" class="controllers">flash</a> object</li>
<li><code>grailsApplication</code> - The <a href="../api/org/codehaus/groovy/grails/commons/GrailsApplication.html" class="api">GrailsApplication</a> instance</li>
<li><code>out</code> - The response writer for writing to the output stream</li>
<li><code>params</code> - The <a href="../ref/Controllers/params.html" class="controllers">params</a> object for retrieving request parameters</li>
<li><code>request</code> - The <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletRequest.html" class="api">HttpServletRequest</a> instance</li>
<li><code>response</code> - The <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletResponse.html" class="api">HttpServletResponse</a> instance</li>
<li><code>session</code> - The <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpSession.html" class="api">HttpSession</a> instance</li>
<li><code>webRequest</code> - The <a href="../api/org/codehaus/groovy/grails/web/servlet/mvc/GrailsWebRequest.html" class="api">GrailsWebRequest</a> instance</li>
</ul><p class="paragraph"/>

<a name="6.2.2.2 Logic and Iteration"><!-- Legacy link --></a>
<h2 id="logicAndIteration">7.2.1.2 Logic and Iteration</h2>
Using the <code>&#60;% %&#62;</code> syntax you can embed loops and so on using this syntax:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
      <span class="xml&#45;tag">&#60;% &#91;1,2,3,4&#93;.each &#123; num &#45;&#62;</span> %&#62;
         <span class="xml&#45;tag">&#60;p&#62;</span><span class="xml&#45;tag">&#60;%=<span class="xml&#45;quote">"Hello $&#123;num&#125;!"</span> %&#62;</span><span class="xml&#45;tag">&#60;/p&#62;</span>
      <span class="xml&#45;tag">&#60;%&#125;%&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>As well as logical branching:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
      <span class="xml&#45;tag">&#60;% if (params.hello == 'true')%&#62;</span>
      <span class="xml&#45;tag">&#60;%=<span class="xml&#45;quote">"Hello!"</span>%&#62;</span>
      <span class="xml&#45;tag">&#60;% else %&#62;</span>
      <span class="xml&#45;tag">&#60;%=<span class="xml&#45;quote">"Goodbye!"</span>%&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div>


<a name="6.2.1.3 Page Directives"><!-- Legacy link --></a>
<h2 id="pageDirectives">7.2.1.3 Page Directives</h2>
GSP also supports a few JSP-style page directives.<p class="paragraph"/>The import directive lets you import classes into the page. However, it is rarely needed due to Groovy's default imports and <a href="../guide/single.html#tags" class="guide">GSP Tags</a>:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;%@ page import=<span class="xml&#45;quote">"java.awt.&#42;"</span> %&#62;</span></pre></div><p class="paragraph"/>GSP also supports the contentType directive:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;%@ page contentType=<span class="xml&#45;quote">"text/json"</span> %&#62;</span></pre></div><p class="paragraph"/>The contentType directive allows using GSP to render other formats.


<a name="6.2.1.4 Expressions"><!-- Legacy link --></a>
<h2 id="expressions">7.2.1.4 Expressions</h2>
In GSP the <code>&#60;%= %&#62;</code> syntax introduced earlier is rarely used due to the support for GSP expressions. A GSP expression is similar to a JSP EL expression or a Groovy GString and takes the form <code>${expr}</code>:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
  <span class="xml&#45;tag">&#60;body&#62;</span>
    Hello $&#123;params.name&#125;
  <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>However, unlike JSP EL you can have any Groovy expression within the <code>${..}</code> block. Variables within the <code>${..}</code> block are <strong class="bold">not</strong> escaped by default, so any HTML in the variable's string is rendered directly to the page. To reduce the risk of Cross-site-scripting (XSS) attacks, you can enable automatic HTML escaping with the <code>grails.views.default.codec</code> setting in <code>grails-app/conf/Config.groovy</code>:<p class="paragraph"/><div class="code"><pre>grails.views.<span class="java&#45;keyword">default</span>.codec='html'</pre></div><p class="paragraph"/>Other possible values are 'none' (for no default encoding) and 'base64'.


<a name="6.2.2 GSP Tags"><!-- Legacy link --></a>
<h2 id="tags">7.2.2 GSP Tags</h2>
Now that the less attractive JSP heritage has been set aside, the following sections cover GSP's built-in tags, which are the preferred way to define GSP pages.<p class="paragraph"/><blockquote class="note">
The section on <a href="../guide/single.html#taglibs" class="guide">Tag Libraries</a> covers how to add your own custom tag libraries.
</blockquote><p class="paragraph"/>All built-in GSP tags start with the prefix <code>g:</code>. Unlike JSP, you don't specify any tag library imports. If a tag starts with <code>g:</code> it is automatically assumed to be a GSP tag. An example GSP tag would look like:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:example /&#62;</span></pre></div><p class="paragraph"/>GSP tags can also have a body such as:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:example&#62;</span>
   Hello world
<span class="xml&#45;tag">&#60;/g:example&#62;</span></pre></div><p class="paragraph"/>Expressions can be passed into GSP tag attributes, if an expression is not used it will be assumed to be a String value:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:example attr=<span class="xml&#45;quote">"$&#123;new Date()&#125;"</span>&#62;</span>
   Hello world
<span class="xml&#45;tag">&#60;/g:example&#62;</span></pre></div><p class="paragraph"/>Maps can also be passed into GSP tag attributes, which are often used for a named parameter style syntax:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:example attr=<span class="xml&#45;quote">"$&#123;new Date()&#125;"</span> attr2=<span class="xml&#45;quote">"&#91;one:1, two:2, three:3&#93;"</span>&#62;</span>
   Hello world
<span class="xml&#45;tag">&#60;/g:example&#62;</span></pre></div><p class="paragraph"/>Note that within the values of attributes you must use single quotes for Strings:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:example attr=<span class="xml&#45;quote">"$&#123;new Date()&#125;"</span> attr2=<span class="xml&#45;quote">"&#91;one:'one', two:'two'&#93;"</span>&#62;</span>
   Hello world
<span class="xml&#45;tag">&#60;/g:example&#62;</span></pre></div><p class="paragraph"/>With the basic syntax out the way, the next sections look at the tags that are built into Grails by default.



<h2 id="tagVariablesAndScopes">7.2.2.1 Variables and Scopes</h2>
Variables can be defined within a GSP using the <a href="../ref/Tags/set.html" class="tags">set</a> tag:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:set var=<span class="xml&#45;quote">"now"</span> value=<span class="xml&#45;quote">"$&#123;new Date()&#125;"</span> /&#62;</span></pre></div><p class="paragraph"/>Here we assign a variable called <code>now</code> to the result of a GSP expression (which simply constructs a new <code>java.util.Date</code> instance). You can also use the body of the <code>&#60;g:set&#62;</code> tag to define a variable:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:set var=<span class="xml&#45;quote">"myHTML"</span>&#62;</span>
   Some re&#45;usable code on: $&#123;new Date()&#125;
<span class="xml&#45;tag">&#60;/g:set&#62;</span></pre></div><p class="paragraph"/>The assigned value can also be a bean from the applicationContext:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:set var=<span class="xml&#45;quote">"bookService"</span> bean=<span class="xml&#45;quote">"bookService"</span> /&#62;</span></pre></div><p class="paragraph"/>Variables can also be placed in one of the following scopes:
<ul class="star">
<li><code>page</code> - Scoped to the current page (default)</li>
<li><code>request</code> - Scoped to the current request</li>
<li><code>flash</code> - Placed within <a href="../ref/Controllers/flash.html" class="controllers">flash</a> scope and hence available for the next request</li>
<li><code>session</code> - Scoped for the user session</li>
<li><code>application</code> - Application-wide scope.</li>
</ul><p class="paragraph"/>To specify the scope, use the <code>scope</code> attribute:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:set var=<span class="xml&#45;quote">"now"</span> value=<span class="xml&#45;quote">"$&#123;new Date()&#125;"</span> scope=<span class="xml&#45;quote">"request"</span> /&#62;</span></pre></div>



<h2 id="tagLogicAndIteration">7.2.2.2 Logic and Iteration</h2>
GSP also supports logical and iterative tags out of the box. For logic there are <a href="../ref/Tags/if.html" class="tags">if</a>, <a href="../ref/Tags/else.html" class="tags">else</a> and <a href="../ref/Tags/elseif.html" class="tags">elseif</a> tags for use with branching:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:if test=<span class="xml&#45;quote">"$&#123;session.role == 'admin'&#125;"</span>&#62;</span>
   <span class="xml&#45;tag">&#60;%&#45;&#45; show administrative functions &#45;&#45;%&#62;</span>
<span class="xml&#45;tag">&#60;/g:if&#62;</span>
<span class="xml&#45;tag">&#60;g:else&#62;</span>
   <span class="xml&#45;tag">&#60;%&#45;&#45; show basic functions &#45;&#45;%&#62;</span>
<span class="xml&#45;tag">&#60;/g:else&#62;</span></pre></div><p class="paragraph"/>Use the <a href="../ref/Tags/each.html" class="tags">each</a> and <a href="../ref/Tags/while.html" class="tags">while</a> tags for iteration:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:each in=<span class="xml&#45;quote">"$&#123;&#91;1,2,3&#93;&#125;"</span> var=<span class="xml&#45;quote">"num"</span>&#62;</span>
   <span class="xml&#45;tag">&#60;p&#62;</span>Number $&#123;num&#125;<span class="xml&#45;tag">&#60;/p&#62;</span>
<span class="xml&#45;tag">&#60;/g:each&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:set var=<span class="xml&#45;quote">"num"</span> value=<span class="xml&#45;quote">"$&#123;1&#125;"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;g:while test=<span class="xml&#45;quote">"$&#123;num &#60; 5 &#125;"</span>&#62;</span>
    <span class="xml&#45;tag">&#60;p&#62;</span>Number $&#123;num++&#125;<span class="xml&#45;tag">&#60;/p&#62;</span>
<span class="xml&#45;tag">&#60;/g:while&#62;</span></pre></div>


<a name="6.2.2.3 Search and Filtering"><!-- Legacy link --></a>
<h2 id="searchAndFiltering">7.2.2.3 Search and Filtering</h2>
If you have collections of objects you often need to sort and filter them. Use the <a href="../ref/Tags/findAll.html" class="tags">findAll</a> and <a href="../ref/Tags/grep.html" class="tags">grep</a> tags for these tasks:<p class="paragraph"/><div class="code"><pre>Stephen King's Books:
<span class="xml&#45;tag">&#60;g:findAll in=<span class="xml&#45;quote">"$&#123;books&#125;"</span> expr=<span class="xml&#45;quote">"it.author == 'Stephen King'"</span>&#62;</span>
     <span class="xml&#45;tag">&#60;p&#62;</span>Title: $&#123;it.title&#125;<span class="xml&#45;tag">&#60;/p&#62;</span>
<span class="xml&#45;tag">&#60;/g:findAll&#62;</span></pre></div><p class="paragraph"/>The <code>expr</code> attribute contains a Groovy expression that can be used as a filter. The <a href="../ref/Tags/grep.html" class="tags">grep</a> tag does a similar job, for example filtering by class:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:grep in=<span class="xml&#45;quote">"$&#123;books&#125;"</span> filter=<span class="xml&#45;quote">"NonFictionBooks.class"</span>&#62;</span>
     <span class="xml&#45;tag">&#60;p&#62;</span>Title: $&#123;it.title&#125;<span class="xml&#45;tag">&#60;/p&#62;</span>
<span class="xml&#45;tag">&#60;/g:grep&#62;</span></pre></div><p class="paragraph"/>Or using a regular expression:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:grep in=<span class="xml&#45;quote">"$&#123;books.title&#125;"</span> filter=<span class="xml&#45;quote">"~/.&#42;?Groovy.&#42;?/"</span>&#62;</span>
     <span class="xml&#45;tag">&#60;p&#62;</span>Title: $&#123;it&#125;<span class="xml&#45;tag">&#60;/p&#62;</span>
<span class="xml&#45;tag">&#60;/g:grep&#62;</span></pre></div><p class="paragraph"/>The above example is also interesting due to its usage of GPath. GPath is an XPath-like language in Groovy. The <code>books</code> variable is a collection of <code>Book</code> instances. Since each <code>Book</code> has a <code>title</code>, you can obtain a list of Book titles using the expression <code>books.title</code>. Groovy will auto-magically iterate the collection, obtain each title, and return a new list!


<a name="6.2.2.4 Links and Resources"><!-- Legacy link --></a>
<h2 id="linksAndResources">7.2.2.4 Links and Resources</h2>
GSP also features tags to help you manage linking to controllers and actions. The <a href="../ref/Tags/link.html" class="tags">link</a> tag lets you specify controller and action name pairing and it will automatically work out the link based on the <a href="../guide/single.html#urlmappings" class="guide">URL Mappings</a>, even if you change them! For example:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:link action=<span class="xml&#45;quote">"show"</span> id=<span class="xml&#45;quote">"1"</span>&#62;</span>Book 1<span class="xml&#45;tag">&#60;/g:link&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:link action=<span class="xml&#45;quote">"show"</span> id=<span class="xml&#45;quote">"$&#123;currentBook.id&#125;"</span>&#62;</span>$&#123;currentBook.name&#125;<span class="xml&#45;tag">&#60;/g:link&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:link controller=<span class="xml&#45;quote">"book"</span>&#62;</span>Book Home<span class="xml&#45;tag">&#60;/g:link&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:link controller=<span class="xml&#45;quote">"book"</span> action=<span class="xml&#45;quote">"list"</span>&#62;</span>Book List<span class="xml&#45;tag">&#60;/g:link&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:link url=<span class="xml&#45;quote">"&#91;action: 'list', controller: 'book'&#93;"</span>&#62;</span>Book List<span class="xml&#45;tag">&#60;/g:link&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:link params=<span class="xml&#45;quote">"&#91;sort: 'title', order: 'asc', author: currentBook.author&#93;"</span>
        action=<span class="xml&#45;quote">"list"</span>&#62;</span>Book List<span class="xml&#45;tag">&#60;/g:link&#62;</span></pre></div>


<a name="6.2.2.5 Forms and Fields"><!-- Legacy link --></a>
<h2 id="formsAndFields">7.2.2.5 Forms and Fields</h2>
<h4>Form Basics</h4><p class="paragraph"/>GSP supports many different tags for working with HTML forms and fields, the most basic of which is the <a href="../ref/Tags/form.html" class="tags">form</a> tag. This is a controller/action aware version of the regular HTML form tag. The <code>url</code> attribute lets you specify which controller and action to map to:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:form name=<span class="xml&#45;quote">"myForm"</span> url=<span class="xml&#45;quote">"&#91;controller:'book',action:'list'&#93;"</span>&#62;</span>...<span class="xml&#45;tag">&#60;/g:form&#62;</span></pre></div><p class="paragraph"/>In this case we create a form called <code>myForm</code> that submits to the <code>BookController</code>'s <code>list</code> action. Beyond that all of the usual HTML attributes apply.<p class="paragraph"/><h4>Form Fields</h4><p class="paragraph"/>In addition to easy construction of forms, GSP supports custom tags for dealing with different types of fields, including:
<ul class="star">
<li><a href="../ref/Tags/textField.html" class="tags">textField</a> - For input fields of type 'text'</li>
<li><a href="../ref/Tags/passwordField.html" class="tags">passwordField</a> - For input fields of type 'password'</li>
<li><a href="../ref/Tags/checkBox.html" class="tags">checkBox</a> - For input fields of type 'checkbox'</li>
<li><a href="../ref/Tags/radio.html" class="tags">radio</a> - For input fields of type 'radio'</li>
<li><a href="../ref/Tags/hiddenField.html" class="tags">hiddenField</a> - For input fields of type 'hidden'</li>
<li><a href="../ref/Tags/select.html" class="tags">select</a> - For dealing with HTML select boxes</li>
</ul><p class="paragraph"/>Each of these allows GSP expressions for the value:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:textField name=<span class="xml&#45;quote">"myField"</span> value=<span class="xml&#45;quote">"$&#123;myValue&#125;"</span> /&#62;</span></pre></div><p class="paragraph"/>GSP also contains extended helper versions of the above tags such as <a href="../ref/Tags/radioGroup.html" class="tags">radioGroup</a> (for creating groups of <a href="../ref/Tags/radio.html" class="tags">radio</a> tags), <a href="../ref/Tags/localeSelect.html" class="tags">localeSelect</a>, <a href="../ref/Tags/currencySelect.html" class="tags">currencySelect</a> and <a href="../ref/Tags/timeZoneSelect.html" class="tags">timeZoneSelect</a> (for selecting locales, currencies and time zones respectively).<p class="paragraph"/><h4>Multiple Submit Buttons</h4><p class="paragraph"/>The age old problem of dealing with multiple submit buttons is also handled elegantly with Grails using the <a href="../ref/Tags/actionSubmit.html" class="tags">actionSubmit</a> tag. It is just like a regular submit, but lets you specify an alternative action to submit to:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:actionSubmit value=<span class="xml&#45;quote">"Some update label"</span> action=<span class="xml&#45;quote">"update"</span> /&#62;</span></pre></div>


<a name="6.2.2.6 Tags as Method Calls"><!-- Legacy link --></a>
<h2 id="tagsAsMethodCalls">7.2.2.6 Tags as Method Calls</h2>
One major different between GSP tags and other tagging technologies is that GSP tags can be called as either regular tags or as method calls from <a href="../guide/single.html#controllers" class="guide">controllers</a>, <a href="../guide/single.html#taglibs" class="guide">tag libraries</a> or GSP views.<p class="paragraph"/><h4>Tags as method calls from GSPs</h4><p class="paragraph"/>Tags return their results as a String-like object (a <code>StreamCharBuffer</code> which has all of the same methods as String) instead of writing directly to the response when called as methods. For example:<p class="paragraph"/><div class="code"><pre>Static Resource: $&#123;createLinkTo(dir: <span class="xml&#45;quote">"images"</span>, file: <span class="xml&#45;quote">"logo.jpg"</span>)&#125;</pre></div><p class="paragraph"/>This is particularly useful for using a tag within an attribute:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;img src=<span class="xml&#45;quote">"$&#123;createLinkTo(dir: 'images', file: 'logo.jpg')&#125;"</span> /&#62;</span></pre></div><p class="paragraph"/>In view technologies that don't support this feature you have to nest tags within tags, which becomes messy quickly and often has an adverse effect of WYSWIG tools such as Dreamweaver that attempt to render the mark-up as it is not well-formed:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;img src=<span class="xml&#45;quote">"&#60;g:createLinkTo dir="</span>images<span class="xml&#45;quote">" file="</span>logo.jpg<span class="xml&#45;quote">" /&#62;</span>"</span> /&#62;</pre></div><p class="paragraph"/><h4>Tags as method calls from Controllers and Tag Libraries</h4><p class="paragraph"/>You can also invoke tags from controllers and tag libraries. Tags within the default <code>g:</code> <a href="../guide/single.html#namespaces" class="guide">namespace</a> can be invoked without the prefix and a <code>StreamCharBuffer</code> result is returned:<p class="paragraph"/><div class="code"><pre>def imageLocation = createLinkTo(dir:<span class="java&#45;quote">"images"</span>, file:<span class="java&#45;quote">"logo.jpg"</span>).toString()</pre></div><p class="paragraph"/>Prefix the namespace to avoid naming conflicts:<p class="paragraph"/><div class="code"><pre>def imageLocation = g.createLinkTo(dir:<span class="java&#45;quote">"images"</span>, file:<span class="java&#45;quote">"logo.jpg"</span>).toString()</pre></div><p class="paragraph"/>For tags that use a <a href="../guide/single.html#namespaces" class="guide">custom namespace</a>, use that prefix for the method call. For example (from the <a href="http://grails.org/plugin/fckeditor" target="blank">FCK Editor plugin</a>):<p class="paragraph"/><div class="code"><pre>def editor = fckeditor.editor(name: <span class="java&#45;quote">"text"</span>, width: <span class="java&#45;quote">"100%"</span>, height: <span class="java&#45;quote">"400"</span>)</pre></div>


<a name="6.2.3 Views and Templates"><!-- Legacy link --></a>
<h2 id="viewsAndTemplates">7.2.3 Views and Templates</h2>
Grails also has the concept of templates. These are useful for partitioning your views into maintainable chunks, and combined with <a href="../guide/single.html#layouts" class="guide">Layouts</a> provide a highly re-usable mechanism for structured views.<p class="paragraph"/><h4>Template Basics</h4><p class="paragraph"/>Grails uses the convention of placing an underscore before the name of a view to identify it as a template. For example, you might have a template that renders Books located at <code>grails-app/views/book/_bookTemplate.gsp</code>:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;div class=<span class="xml&#45;quote">"book"</span> id=<span class="xml&#45;quote">"$&#123;book?.id&#125;"</span>&#62;</span>
   <span class="xml&#45;tag">&#60;div&#62;</span>Title: $&#123;book?.title&#125;<span class="xml&#45;tag">&#60;/div&#62;</span>
   <span class="xml&#45;tag">&#60;div&#62;</span>Author: $&#123;book?.author?.name&#125;<span class="xml&#45;tag">&#60;/div&#62;</span>
<span class="xml&#45;tag">&#60;/div&#62;</span></pre></div><p class="paragraph"/>Use the <a href="../ref/Tags/render.html" class="tags">render</a> tag to render this template from one of the views in <code>grails-app/views/book</code>:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:render template=<span class="xml&#45;quote">"bookTemplate"</span> model=<span class="xml&#45;quote">"&#91;book: myBook&#93;"</span> /&#62;</span></pre></div><p class="paragraph"/>Notice how we pass into a model to use using the <code>model</code> attribute of the <code>render</code> tag. If you have multiple <code>Book</code> instances you can also render the template for each <code>Book</code> using the render tag with a <code>collection</code> attribute:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:render template=<span class="xml&#45;quote">"bookTemplate"</span> var=<span class="xml&#45;quote">"book"</span> collection=<span class="xml&#45;quote">"$&#123;bookList&#125;"</span> /&#62;</span></pre></div><p class="paragraph"/><h4>Shared Templates</h4><p class="paragraph"/>In the previous example we had a template that was specific to the <code>BookController</code> and its views at <code>grails-app/views/book</code>. However, you may want to share templates across your application.<p class="paragraph"/>In this case you can place them in the root views directory at grails-app/views or any subdirectory below that location, and then with the template attribute use an absolute location starting with <code>/</code> instead of a relative location. For example if you had a template called <code>grails-app/views/shared/_mySharedTemplate.gsp</code>, you would reference it as:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:render template=<span class="xml&#45;quote">"/shared/mySharedTemplate"</span> /&#62;</span></pre></div><p class="paragraph"/>You can also use this technique to reference templates in any directory from any view or controller:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:render template=<span class="xml&#45;quote">"/book/bookTemplate"</span> model=<span class="xml&#45;quote">"&#91;book: myBook&#93;"</span> /&#62;</span></pre></div><p class="paragraph"/><h4>The Template Namespace</h4><p class="paragraph"/>Since templates are used so frequently there is template namespace, called <code>tmpl</code>, available that makes using templates easier. Consider for example the following usage pattern:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:render template=<span class="xml&#45;quote">"bookTemplate"</span> model=<span class="xml&#45;quote">"&#91;book:myBook&#93;"</span> /&#62;</span></pre></div><p class="paragraph"/>This can be expressed with the <code>tmpl</code> namespace as follows:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;tmpl:bookTemplate book=<span class="xml&#45;quote">"$&#123;myBook&#125;"</span> /&#62;</span></pre></div><p class="paragraph"/><h4>Templates in Controllers and Tag Libraries</h4><p class="paragraph"/>You can also render templates from controllers using the <a href="../ref/Controllers/render.html" class="controllers">render</a> controller method. This is useful for <a href="../guide/single.html#ajax" class="guide">Ajax</a> applications where you generate small HTML or data responses to partially update the current page instead of performing new request:<p class="paragraph"/><div class="code"><pre>def bookData() &#123;
    def b = Book.get(params.id)
    render(template:<span class="java&#45;quote">"bookTemplate"</span>, model:&#91;book:b&#93;)
&#125;</pre></div><p class="paragraph"/>The <a href="../ref/Controllers/render.html" class="controllers">render</a> controller method writes directly to the response, which is the most common behaviour. To instead obtain the result of template as a String you can use the <a href="../ref/Tags/render.html" class="tags">render</a> tag:<p class="paragraph"/><div class="code"><pre>def bookData() &#123;
    def b = Book.get(params.id)
    <span class="java&#45;object">String</span> content = g.render(template:<span class="java&#45;quote">"bookTemplate"</span>, model:&#91;book:b&#93;)
    render content
&#125;</pre></div><p class="paragraph"/>Notice the usage of the <code>g</code> namespace which tells Grails we want to use the <a href="../guide/single.html#tagsAsMethodCalls" class="guide">tag as method call</a> instead of the <a href="../ref/Controllers/render.html" class="controllers">render</a> method.


<a name="6.2.4 Layouts with Sitemesh"><!-- Legacy link --></a>
<h2 id="layouts">7.2.4 Layouts with Sitemesh</h2>
<h4>Creating Layouts</h4><p class="paragraph"/>Grails leverages <a href="http://www.opensymphony.com/sitemesh/" target="blank">Sitemesh</a>, a decorator engine, to support view layouts. Layouts are located in the <code>grails-app/views/layouts</code> directory. A typical layout can be seen below:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
    <span class="xml&#45;tag">&#60;head&#62;</span>
        <span class="xml&#45;tag">&#60;title&#62;</span><span class="xml&#45;tag">&#60;g:layoutTitle default=<span class="xml&#45;quote">"An example decorator"</span> /&#62;</span><span class="xml&#45;tag">&#60;/title&#62;</span>
        <span class="xml&#45;tag">&#60;g:layoutHead /&#62;</span>
    <span class="xml&#45;tag">&#60;/head&#62;</span>
    <span class="xml&#45;tag">&#60;body onload=<span class="xml&#45;quote">"$&#123;pageProperty(name:'body.onload')&#125;"</span>&#62;</span>
        <span class="xml&#45;tag">&#60;div class=<span class="xml&#45;quote">"menu"</span>&#62;</span><span class="xml&#45;comment">&#60;!&#45;&#45;my common menu goes here&#45;&#45;&#62;</span><span class="xml&#45;tag">&#60;/menu&#62;</span>
            <span class="xml&#45;tag">&#60;div class=<span class="xml&#45;quote">"body"</span>&#62;</span>
                <span class="xml&#45;tag">&#60;g:layoutBody /&#62;</span>
            <span class="xml&#45;tag">&#60;/div&#62;</span>
        <span class="xml&#45;tag">&#60;/div&#62;</span>
    <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>The key elements are the <a href="../ref/Tags/layoutHead.html" class="tags">layoutHead</a>, <a href="../ref/Tags/layoutTitle.html" class="tags">layoutTitle</a> and <a href="../ref/Tags/layoutBody.html" class="tags">layoutBody</a> tag invocations:
<ul class="star">
<li><code>layoutTitle</code> - outputs the target page's title</li>
<li><code>layoutHead</code> - outputs the target page's head tag contents</li>
<li><code>layoutBody</code> - outputs the target page's body tag contents</li>
</ul><p class="paragraph"/>The previous example also demonstrates the <a href="../ref/Tags/pageProperty.html" class="tags">pageProperty</a> tag which can be used to inspect and return aspects of the target page.<p class="paragraph"/><h4>Triggering Layouts</h4><p class="paragraph"/>There are a few ways to trigger a layout. The simplest is to add a meta tag to the view:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
    <span class="xml&#45;tag">&#60;head&#62;</span>
        <span class="xml&#45;tag">&#60;title&#62;</span>An Example Page<span class="xml&#45;tag">&#60;/title&#62;</span>
        <span class="xml&#45;tag">&#60;meta name=<span class="xml&#45;quote">"layout"</span> content=<span class="xml&#45;quote">"main"</span> /&#62;</span>
    <span class="xml&#45;tag">&#60;/head&#62;</span>
    <span class="xml&#45;tag">&#60;body&#62;</span>This is my content!<span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>In this case a layout called <code>grails-app/views/layouts/main.gsp</code> will be used to layout the page. If we were to use the layout from the previous section the output would resemble this:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
    <span class="xml&#45;tag">&#60;head&#62;</span>
        <span class="xml&#45;tag">&#60;title&#62;</span>An Example Page<span class="xml&#45;tag">&#60;/title&#62;</span>
    <span class="xml&#45;tag">&#60;/head&#62;</span>
    <span class="xml&#45;tag">&#60;body onload=<span class="xml&#45;quote">""</span>&#62;</span>
        <span class="xml&#45;tag">&#60;div class=<span class="xml&#45;quote">"menu"</span>&#62;</span><span class="xml&#45;comment">&#60;!&#45;&#45;my common menu goes here&#45;&#45;&#62;</span><span class="xml&#45;tag">&#60;/div&#62;</span>
        <span class="xml&#45;tag">&#60;div class=<span class="xml&#45;quote">"body"</span>&#62;</span>
            This is my content!
        <span class="xml&#45;tag">&#60;/div&#62;</span>
    <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/><h4>Specifying A Layout In A Controller</h4><p class="paragraph"/>Another way to specify a layout is to specify the name of the layout by assigning a value to the "layout" property in a controller. For example, if you have a controller such as:<p class="paragraph"/><div class="code"><pre>class BookController &#123;
    <span class="java&#45;keyword">static</span> layout = 'customer'<p class="paragraph"/>    def list() &#123; &#8230; &#125;
&#125;</pre></div><p class="paragraph"/>You can create a layout called <code>grails-app/views/layouts/customer.gsp</code> which will be applied to all views that the <code>BookController</code> delegates to.  The value of the "layout" property may contain a directory structure relative to the <code>grails-app/views/layouts/</code> directory.  For example:<p class="paragraph"/><div class="code"><pre>class BookController &#123;
    <span class="java&#45;keyword">static</span> layout = 'custom/customer'<p class="paragraph"/>    def list() &#123; &#8230; &#125;
&#125;</pre></div><p class="paragraph"/>Views rendered from that controller would be decorated with the <code>grails-app/views/layouts/custom/customer.gsp</code> template.<p class="paragraph"/><h4>Layout by Convention</h4><p class="paragraph"/>Another way to associate layouts is to use "layout by convention". For example, if you have this controller:<p class="paragraph"/><div class="code"><pre>class BookController &#123;
    def list() &#123; &#8230; &#125;
&#125;</pre></div><p class="paragraph"/>You can create a layout called <code>grails-app/views/layouts/book.gsp</code>, which will be applied to all views that the <code>BookController</code> delegates to.<p class="paragraph"/>Alternatively, you can create a layout called <code>grails-app/views/layouts/book/list.gsp</code> which will only be applied to the <code>list</code> action within the <code>BookController</code>.<p class="paragraph"/>If you have both the above mentioned layouts in place the layout specific to the action will take precedence when the list action is executed.<p class="paragraph"/>If a layout may not be located using any of those conventions, the convention of last resort is to look for the application default layout which
is <code>grails-app/views/layouts/application.gsp</code>.  The name of the application default layout may be changed by defining a property
in <code>grails-app/conf/Config.groovy</code> as follows:<p class="paragraph"/><div class="code"><pre>grails.sitemesh.<span class="java&#45;keyword">default</span>.layout = 'myLayoutName'</pre></div><p class="paragraph"/>With that property in place, the application default layout will be <code>grails-app/views/layouts/myLayoutName.gsp</code>.<p class="paragraph"/><h4>Inline Layouts</h4><p class="paragraph"/>Grails' also supports Sitemesh's concept of inline layouts with the <a href="../ref/Tags/applyLayout.html" class="tags">applyLayout</a> tag. This can be used to apply a layout to a template, URL or arbitrary section of content. This lets you even further modularize your view structure by "decorating" your template includes.<p class="paragraph"/>Some examples of usage can be seen below:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:applyLayout name=<span class="xml&#45;quote">"myLayout"</span> template=<span class="xml&#45;quote">"bookTemplate"</span> collection=<span class="xml&#45;quote">"$&#123;books&#125;"</span> /&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:applyLayout name=<span class="xml&#45;quote">"myLayout"</span> url=<span class="xml&#45;quote">"http://www.google.com"</span> /&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:applyLayout name=<span class="xml&#45;quote">"myLayout"</span>&#62;</span>
The content to apply a layout to
<span class="xml&#45;tag">&#60;/g:applyLayout&#62;</span></pre></div><p class="paragraph"/><h4>Server-Side Includes</h4><p class="paragraph"/>While the <a href="../ref/Tags/applyLayout.html" class="tags">applyLayout</a> tag is useful for applying layouts to external content, if you simply want to include external content in the current page you use the <a href="../ref/Tags/include.html" class="tags">include</a> tag:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:include controller=<span class="xml&#45;quote">"book"</span> action=<span class="xml&#45;quote">"list"</span> /&#62;</span></pre></div><p class="paragraph"/>You can even combine the <a href="../ref/Tags/include.html" class="tags">include</a> tag and the <a href="../ref/Tags/applyLayout.html" class="tags">applyLayout</a> tag for added flexibility:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:applyLayout name=<span class="xml&#45;quote">"myLayout"</span>&#62;</span>
   <span class="xml&#45;tag">&#60;g:include controller=<span class="xml&#45;quote">"book"</span> action=<span class="xml&#45;quote">"list"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;/g:applyLayout&#62;</span></pre></div><p class="paragraph"/>Finally, you can also call the <a href="../ref/Tags/include.html" class="tags">include</a> tag from a controller or tag library as a method:<p class="paragraph"/><div class="code"><pre>def content = include(controller:<span class="java&#45;quote">"book"</span>, action:<span class="java&#45;quote">"list"</span>)</pre></div><p class="paragraph"/>The resulting content will be provided via the return value of the <a href="../ref/Tags/include.html" class="tags">include</a> tag.


<a name="6.2.5 Static Resources"><!-- Legacy link --></a>
<h2 id="resources">7.2.5 Static Resources</h2>
Grails 2.0 integrates with the <a href="http://grails.org/plugin/resources" target="blank">Resources plugin</a> to provide sophisticated static resource management. This plugin is installed by default in new Grails applications.<p class="paragraph"/>The basic way to include a link to a static resource in your application is to use the <a href="../ref/Tags/resource.html" class="tags">resource</a> tag. This simple approach creates a URI pointing to the file.<p class="paragraph"/>However modern applications with dependencies on multiple JavaScript and CSS libraries and frameworks (as well as dependencies on multiple Grails plugins) require something more powerful.<p class="paragraph"/>The issues that the Resources framework tackles are:
<ul class="star">
<li>Web application performance tuning is difficult</li>
<li>Correct ordering of resources, and deferred inclusion of JavaScript</li>
<li>Resources that depend on others that must be loaded first</li>
<li>The need for a standard way to expose static resources in plugins and applications</li>
<li>The need for an extensible processing chain to optimize resources</li>
<li>Preventing multiple inclusion of the same resource</li>
</ul><p class="paragraph"/>The plugin achieves this by introducing new artefacts and processing the resources using the server's local file system.<p class="paragraph"/>It adds artefacts for declaring resources, for declaring "mappers" that can process resources, and a servlet filter to serve processed resources.<p class="paragraph"/>What you get is an incredibly advanced resource system that enables you to easily create highly optimized web applications that run the same in development and in production.<p class="paragraph"/>The Resources plugin documentation provides a more detailed overview of the <a href="http://grails-plugins.github.com/grails-resources/" target="blank">concepts</a> which will be beneficial when reading the following guide.


<a name="6.2.5.1 Including resources using the resource tags"><!-- Legacy link --></a>
<h2 id="includingResourcesUsingTheResourceTags">7.2.5.1 Including resources using the resource tags</h2>
<h4>Pulling in resources with r:require</h4><p class="paragraph"/>To use resources, your GSP page must indicate which resource modules it requires. For example with the <a href="http://grails.org/plugin/jquery" target="blank">jQuery plugin</a>, which exposes a "jquery" resource module, to use jQuery in any page on your site you simply add:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;head&#62;</span>
      <span class="xml&#45;tag">&#60;r:require module=<span class="xml&#45;quote">"jquery"</span>/&#62;</span>
      <span class="xml&#45;tag">&#60;r:layoutResources/&#62;</span>
   <span class="xml&#45;tag">&#60;/head&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
      &#8230;
      <span class="xml&#45;tag">&#60;r:layoutResources/&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>This will automatically include all resources needed for jQuery, including them at the correct locations in the page. By default the plugin sets the disposition to be "head", so they load early in the page.<p class="paragraph"/>You can call <code>r:require</code> multiple times in a GSP page, and you use the "modules" attribute to provide a list of modules:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;head&#62;</span>
      <span class="xml&#45;tag">&#60;r:require modules=<span class="xml&#45;quote">"jquery, main, blueprint, charting"</span>/&#62;</span>
      <span class="xml&#45;tag">&#60;r:layoutResources/&#62;</span>
   <span class="xml&#45;tag">&#60;/head&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
      &#8230;
      <span class="xml&#45;tag">&#60;r:layoutResources/&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>The above may result in many JavaScript and CSS files being included, in the correct order, with some JavaScript files loading at the end of the body to improve the apparent page load time.<p class="paragraph"/>However you cannot use r:require in isolation - as per the examples you must have the &#60;r:layoutResources/&#62; tag to actually perform the render.<p class="paragraph"/><h4>Rendering the links to resources with r:layoutResources</h4><p class="paragraph"/>When you have declared the resource modules that your GSP page requires, the framework needs to render the links to those resources at the correct time.<p class="paragraph"/>To achieve this correctly, you must include the r:layoutResources tag twice in your page, or more commonly, in your GSP layout:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;head&#62;</span>
      <span class="xml&#45;tag">&#60;g:layoutTitle/&#62;</span>
      <span class="xml&#45;tag">&#60;r:layoutResources/&#62;</span>
   <span class="xml&#45;tag">&#60;/head&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
      <span class="xml&#45;tag">&#60;g:layoutBody/&#62;</span>
      <span class="xml&#45;tag">&#60;r:layoutResources/&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>This represents the simplest Sitemesh layout you can have that supports Resources.<p class="paragraph"/>The Resources framework has the concept of a "disposition" for every resource. This is an indication of where in the page the resource should be included.<p class="paragraph"/>The default disposition applied depends on the type of resource. All CSS must be rendered in &#60;head&#62; in HTML, so "head" is the default for all CSS, and will be rendered by the first r:layoutResources. Page load times are improved when JavaScript is loaded after the page content, so the default for JavaScript files is "defer", which means it is rendered when the second r:layoutResources is invoked.<p class="paragraph"/>Note that both your GSP page and your Sitemesh layout (as well as any GSP template fragments) can call r:require to depend on resources. The only limitation is that you must call r:require before the r:layoutResources that should render it.<p class="paragraph"/><h4>Adding page-specific JavaScript code with r:script</h4><p class="paragraph"/>Grails has the <a href="../ref/Tags/javascript.html" class="tags">javascript</a> tag which is adapted to defer to Resources plugin if installed, but it is recommended that you call <code>r:script</code> directly when you need to include fragments of JavaScript code.<p class="paragraph"/>This lets you write some "inline" JavaScript which is actually <strong class="bold">not</strong> rendered inline, but either in the &#60;head&#62; or at the end of the body, based on the disposition.<p class="paragraph"/>Given a Sitemesh layout like this:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;head&#62;</span>
      <span class="xml&#45;tag">&#60;g:layoutTitle/&#62;</span>
      <span class="xml&#45;tag">&#60;r:layoutResources/&#62;</span>
   <span class="xml&#45;tag">&#60;/head&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
      <span class="xml&#45;tag">&#60;g:layoutBody/&#62;</span>
      <span class="xml&#45;tag">&#60;r:layoutResources/&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>...in your GSP you can inject some JavaScript code into the head or deferred regions of the page like this:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;head&#62;</span>
      <span class="xml&#45;tag">&#60;title&#62;</span>Testing r:script magic!<span class="xml&#45;tag">&#60;/title&#62;</span>
   <span class="xml&#45;tag">&#60;/head&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
      <span class="xml&#45;tag">&#60;r:script disposition=<span class="xml&#45;quote">"head"</span>&#62;</span>
         window.alert('This is at the end of <span class="xml&#45;tag">&#60;head&#62;</span>');
      <span class="xml&#45;tag">&#60;/r:script&#62;</span>
      <span class="xml&#45;tag">&#60;r:script disposition=<span class="xml&#45;quote">"defer"</span>&#62;</span>
         window.alert('This is at the end of the body, and the page has loaded.');
      <span class="xml&#45;tag">&#60;/r:script&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>The default disposition is "defer", so the disposition in the latter r:script is purely included for demonstration.<p class="paragraph"/>Note that such r:script code fragments <strong class="bold">always</strong> load after any modules that you have used, to ensure that any required libraries have loaded.<p class="paragraph"/><h4>Linking to images with r:img</h4><p class="paragraph"/>This tag is used to render <code>&#60;img&#62;</code> markup, using the Resources framework to process the resource on the fly (if configured to do so - e.g. make it eternally cacheable).<p class="paragraph"/>This includes any extra attributes on the <code>&#60;img&#62;</code> tag if the resource has been previously declared in a module.<p class="paragraph"/>With this mechanism you can specify the width, height and any other attributes in the resource declaration in the module, and they will be pulled in as necessary.<p class="paragraph"/>Example:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
   <span class="xml&#45;tag">&#60;head&#62;</span>
      <span class="xml&#45;tag">&#60;title&#62;</span>Testing r:img<span class="xml&#45;tag">&#60;/title&#62;</span>
   <span class="xml&#45;tag">&#60;/head&#62;</span>
   <span class="xml&#45;tag">&#60;body&#62;</span>
      <span class="xml&#45;tag">&#60;r:img uri=<span class="xml&#45;quote">"/images/logo.png"</span>/&#62;</span>
   <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div><p class="paragraph"/>Note that Grails has a built-in <code>g:img</code> tag as a shortcut for rendering <code>&#60;img&#62;</code> tags that refer to a static resource. The Grails <a href="../ref/Tags/img.html" class="tags">img</a> tag is Resources-aware and will delegate to <code>r:img</code> if found. However it is recommended that you use <code>r:img</code> directly if using the Resources plugin.<p class="paragraph"/>Alongside the regular Grails <a href="../ref/Tags/resource.html" class="tags">resource</a> tag attributes, this also supports the "uri" attribute for increased brevity.<p class="paragraph"/>See <a href="http://grails-plugins.github.com/grails-resources" target="blank">r:resource documentation</a> for full details.


<a name="6.2.5.2 Other resource tags"><!-- Legacy link --></a>
<h2 id="otherResourceTags">7.2.5.2 Other resource tags</h2>
<h4>r:resource</h4><p class="paragraph"/>This is equivalent to the Grails <a href="../ref/Tags/resource.html" class="Tags">resource</a> tag, returning a link to the processed static resource. Grails' own <code>g:resource</code> tag delegates to this implementation if found, but if your code requires the Resources plugin, you should use <code>r:resource</code> directly.<p class="paragraph"/>Alongside the regular Grails <a href="../ref/Tags/resource.html" class="Tags">resource</a> tag attributes, this also supports the "uri" attribute for increased brevity.<p class="paragraph"/>See <a href="http://grails-plugins.github.com/grails-resources" target="blank">r:resource documentation</a> for full details.<p class="paragraph"/><h4>r:external</h4><p class="paragraph"/>This is a resource-aware version of Grails <a href="../ref/Tags/external.html" class="Tags">external</a> tag which renders the HTML markup necessary to include an external file resource such as CSS, JS or a favicon.<p class="paragraph"/>See <a href="http://grails-plugins.github.com/grails-resources" target="blank">r:resource documentation</a> for full details.


<a name="6.2.5.3 Declaring resources"><!-- Legacy link --></a>
<h2 id="declaringResources">7.2.5.3 Declaring resources</h2>
A DSL is provided for declaring resources and modules. This can go either in your <code>Config.groovy</code> in the case of application-specific resources, or more commonly in a resources artefact in <code>grails-app/conf</code>.<p class="paragraph"/>Note that you do not need to declare all your static resources, especially images. However you must to establish dependencies or other resources-specific attributes. Any resource that is not declared is called "ad-hoc" and will still be processed using defaults for that resource type.<p class="paragraph"/>Consider this example resource configuration file, <code>grails-app/conf/MyAppResources.groovy</code>:<p class="paragraph"/><div class="code"><pre>modules = &#123;
    core &#123;
        dependsOn 'jquery, utils'<p class="paragraph"/>        resource url: '/js/core.js', disposition: 'head'
        resource url: '/js/ui.js'
        resource url: '/css/main.css',
        resource url: '/css/branding.css'
        resource url: '/css/print.css', attrs: &#91;media: 'print'&#93;
    &#125;<p class="paragraph"/>    utils &#123;
        dependsOn 'jquery'<p class="paragraph"/>        resource url: '/js/utils.js'
    &#125;<p class="paragraph"/>    forms &#123;
        dependsOn 'core,utils'<p class="paragraph"/>        resource url: '/css/forms.css'
        resource url: '/js/forms.js'
    &#125;
&#125;</pre></div><p class="paragraph"/>This defines three resource modules; 'core', 'utils' and 'forms'. The resources in these modules will be automatically bundled out of the box according to the module name, resulting in fewer files. You can override this with <code>bundle:'someOtherName'</code> on each resource, or call <code>defaultBundle</code> on the module (see <a href="http://grails-plugins.github.com/grails-resources" target="blank">resources plugin documentation</a>).<p class="paragraph"/>It declares dependencies between them using <code>dependsOn</code>, which controls the load order of the resources.<p class="paragraph"/>When you include an <code>&#60;r:require module="forms"/&#62;</code> in your GSP, it will pull in all the resources from 'core' and 'utils' as well as 'jquery', all in the correct order.<p class="paragraph"/>You'll also notice the <code>disposition:'head'</code> on the <code>core.js</code> file. This tells Resources that while it can defer all the other JS files to the end of the body, this one must go into the <code>&#60;head&#62;</code>.<p class="paragraph"/>The CSS file for print styling adds custom attributes using the <code>attrs</code> map option, and these are passed through to the <code>r:external</code> tag when the engine renders the link to the resource, so you can customize the HTML attributes of the generated link.<p class="paragraph"/>There is no limit to the number of modules or xxxResources.groovy artefacts you can provide, and plugins can supply them to expose modules to applications, which is exactly how the jQuery plugin works.<p class="paragraph"/>To define modules like this in your application's Config.groovy, you simply assign the DSL closure to the <code>grails.resources.modules</code> Config variable.<p class="paragraph"/>For full details of the resource DSL please see the <a href="http://grails-plugins.github.com/grails-resources" target="blank">resources plugin documentation</a>.


<a name="6.2.5.4 Overriding plugin resources"><!-- Legacy link --></a>
<h2 id="overridingPluginResources">7.2.5.4 Overriding plugin resources</h2>
Because a resource module can define the bundle groupings and other attributes of resources, you may find that the settings provided are not correct for your application.<p class="paragraph"/>For example, you may wish to bundle jQuery and some other libraries all together in one file. There is a load-time and caching trade-off here, but often it is the case that you'd like to override some of these settings.<p class="paragraph"/>To do this, the DSL supports an "overrides" clause, within which you can change the <code>defaultBundle</code> setting for a module, or attributes of individual resources that have been declared with a unique id:<p class="paragraph"/><div class="code"><pre>modules = &#123;
    core &#123;
        dependsOn 'jquery, utils'
        defaultBundle 'monolith'<p class="paragraph"/>        resource url: '/js/core.js', disposition: 'head'
        resource url: '/js/ui.js'
        resource url: '/css/main.css',
        resource url: '/css/branding.css'
        resource url: '/css/print.css', attrs: &#91;media: 'print'&#93;
    &#125;<p class="paragraph"/>    utils &#123;
        dependsOn 'jquery'
        defaultBundle 'monolith'<p class="paragraph"/>        resource url: '/js/utils.js'
    &#125;<p class="paragraph"/>    forms &#123;
        dependsOn 'core,utils'
        defaultBundle 'monolith'<p class="paragraph"/>        resource url: '/css/forms.css'
        resource url: '/js/forms.js'
    &#125;<p class="paragraph"/>    overrides &#123;
        jquery &#123;
            defaultBundle 'monolith'
        &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/>This will put all code into a single bundle named 'monolith'. Note that this can still result in multiple files, as separate bundles are required for head and defer dispositions, and JavaScript and CSS files are bundled separately.<p class="paragraph"/>Note that overriding individual resources requires the original declaration to have included a unique id for the resource.<p class="paragraph"/>For full details of the resource DSL please see the <a href="http://grails-plugins.github.com/grails-resources" target="blank">resources plugin documentation</a>.


<a name="6.2.5.5 Optimizing your resources"><!-- Legacy link --></a>
<h2 id="optimizingYourResources">7.2.5.5 Optimizing your resources</h2>
The Resources framework uses "mappers" to mutate the resources into the final format served to the user.<p class="paragraph"/>The resource mappers are applied to each static resource once, in a specific order. You can create your own resource mappers, and several plugins provide some already for zipping, caching and minifying.<p class="paragraph"/>Out of the box, the Resources plugin provides bundling of resources into fewer files, which is achieved with a few mappers that also perform CSS re-writing to handle when your CSS files are moved into a bundle.<p class="paragraph"/><h4>Bundling multiple resources into fewer files</h4><p class="paragraph"/>The 'bundle' mapper operates by default on any resource with a "bundle" defined - or inherited from a <code>defaultBundle</code> clause on the module. Modules have an implicit default bundle name the same as the name of the module.<p class="paragraph"/>Files of the same kind will be aggregated into this bundle file. Bundles operate across module boundaries:<p class="paragraph"/><div class="code"><pre>modules = &#123;
    core &#123;
        dependsOn 'jquery, utils'
        defaultBundle 'common'<p class="paragraph"/>        resource url: '/js/core.js', disposition: 'head'
        resource url: '/js/ui.js', bundle: 'ui'
        resource url: '/css/main.css', bundle: 'theme'
        resource url: '/css/branding.css'
        resource url: '/css/print.css', attrs: &#91;media: 'print'&#93;
    &#125;<p class="paragraph"/>    utils &#123;
        dependsOn 'jquery'<p class="paragraph"/>        resource url: '/js/utils.js', bundle: 'common'
    &#125;<p class="paragraph"/>    forms &#123;
        dependsOn 'core,utils'<p class="paragraph"/>        resource url: '/css/forms.css', bundle: 'ui'
        resource url: '/js/forms.js', bundle: 'ui'
    &#125;
&#125;</pre></div><p class="paragraph"/>Here you see that resources are grouped into bundles; 'common', 'ui' and 'theme' - across module boundaries.<p class="paragraph"/>Note that auto-bundling by module does <strong class="bold">not</strong> occur if there is only one resource in the module.<p class="paragraph"/><h4>Making resources cache "eternally" in the client browser</h4><p class="paragraph"/>Caching resources "eternally" in the client is only viable if the resource has a unique name that changes whenever the contents change, and requires caching headers to be set on the response.<p class="paragraph"/>The <a href="http://grails.org/plugin/cached-resources" target="blank">cached-resources</a> plugin provides a mapper that achieves this by hashing your files and renaming them based on this hash. It also sets the caching headers on every response for those resources. To use, simply install the cached-resources plugin.<p class="paragraph"/>Note that the caching headers can only be set if your resources are being served by your application. If you have another server serving the static content from your app (e.g. Apache HTTPD), configure it to send caching headers. Alternatively you can configure it to request and proxy the resources from your container.<p class="paragraph"/><h4>Zipping resources</h4><p class="paragraph"/>Returning gzipped resources is another way to reduce page load times and reduce bandwidth.<p class="paragraph"/>The <a href="http://grails.org/plugin/zipped-resources" target="blank">zipped-resources</a> plugin provides a mapper that automatically compresses your content, excluding by default already compressed formats such as gif, jpeg and png.<p class="paragraph"/>Simply install the zipped-resources plugin and it works.<p class="paragraph"/><h4>Minifying</h4><p class="paragraph"/>There are a number of CSS and JavaScript minifiers available to obfuscate and reduce the size of your code. At the time of writing none are publicly released but releases are imminent.


<a name="6.2.5.6 Debugging"><!-- Legacy link --></a>
<h2 id="debugging">7.2.5.6 Debugging</h2>
When your resources are being moved around, renamed and otherwise mutated, it can be hard to debug client-side issues. Modern browsers, especially Safari, Chrome and Firefox have excellent tools that let you view all the resources requested by a page, including the headers and other information about them.<p class="paragraph"/>There are several debugging features built in to the Resources framework.<p class="paragraph"/><h4>X-Grails-Resources-Original-Src Header</h4><p class="paragraph"/>Every resource served in development mode will have the X-Grails-Resources-Original-Src: header added, indicating the original source file(s) that make up the response.<p class="paragraph"/><h4>Adding the debug flag</h4><p class="paragraph"/>If you add a query parameter <strong class="bold">_debugResources=y</strong> to your URL and request the page, Resources will bypass any processing so that you can see your original source files.<p class="paragraph"/>This also adds a unique timestamp to all your resource URLs, to defeat any caching that browsers may use. This means that you should always see your very latest code when you reload the page.<p class="paragraph"/><h4>Turning on debug all the time</h4><p class="paragraph"/>You can turn on the aforementioned debug mechanism without requiring a query parameter, but turning it on in Config.groovy:<p class="paragraph"/><div class="code"><pre>grails.resources.debug = <span class="java&#45;keyword">true</span></pre></div><p class="paragraph"/>You can of course set this per-environment.


<a name="6.2.5.7 Preventing processing of resources"><!-- Legacy link --></a>
<h2 id="preventingProcessingOfResources">7.2.5.7 Preventing processing of resources</h2>
Sometimes you do not want a resource to be processed in a particular way, or even at all. Occasionally you may also want to disable all resource mapping.<p class="paragraph"/><h4>Preventing the application of a specific mapper to an individual resource</h4><p class="paragraph"/>All resource declarations support a convention of noXXXX:true where XXXX is a mapper name.<p class="paragraph"/>So for example to prevent the "hashandcache" mapper from being applied to a resource (which renames and moves it, potentially breaking relative links written in JavaScript code), you would do this:<p class="paragraph"/><div class="code"><pre>modules = &#123;
    forms &#123;
        resource url: '/css/forms.css', nohashandcache: <span class="java&#45;keyword">true</span>
        resource url: '/js/forms.js', nohashandcache: <span class="java&#45;keyword">true</span>
    &#125;
&#125;</pre></div><p class="paragraph"/><h4>Excluding/including paths and file types from specific mappers</h4><p class="paragraph"/>Mappers have includes/excludes Ant patterns to control whether they apply to a given resource. Mappers set sensible defaults for these based on their activity, for example the zipped-resources plugin's "zip" mapper is set to exclude images by default.<p class="paragraph"/>You can configure this in your <code>Config.groovy</code> using the mapper name e.g:<p class="paragraph"/><div class="code"><pre>// We wouldn't link to .exe files using Resources but <span class="java&#45;keyword">for</span> the sake of example:
grails.resources.zip.excludes = &#91;'&#42;&#42;/&#42;.zip', '&#42;&#42;/&#42;.exe'&#93;<p class="paragraph"/>// Perhaps <span class="java&#45;keyword">for</span> some reason we want to prevent bundling on <span class="java&#45;quote">"less"</span> CSS files:
grails.resources.bundle.excludes = &#91;'&#42;&#42;/&#42;.less'&#93;</pre></div><p class="paragraph"/>There is also an "includes" inverse. Note that settings these replaces the default includes/excludes for that mapper - it is not additive.<p class="paragraph"/><h4>Controlling what is treated as an "ad-hoc" (legacy) resource</h4><p class="paragraph"/>Ad-hoc resources are those undeclared, but linked to directly in your application <strong class="bold">without</strong> using the Grails or Resources linking tags (resource, img or external).<p class="paragraph"/>These may occur with some legacy plugins or code with hardcoded paths in.<p class="paragraph"/>There is a Config.groovy setting <strong class="bold">grails.resources.adhoc.patterns</strong> which defines a list of Servlet API compliant filter URI mappings, which the Resources filter will use to detect such "ad-hoc resource" requests.<p class="paragraph"/>By default this is set to:
<div class="code"><pre>grails.resources.adhoc.patterns = &#91;'images/&#42;', '&#42;.js', '&#42;.css'&#93;</pre></div>


<a name="6.2.5.8 Other Resources-aware plugins"><!-- Legacy link --></a>
<h2 id="otherResourcesPlugins">7.2.5.8 Other Resources-aware plugins</h2>
At the time of writing, the following plugins include support for the Resources framework:
<ul class="star">
<li><a href="http://grails.org/plugin/jquery" target="blank">jquery</a></li>
<li><a href="http://grails.org/plugin/jquery-ui" target="blank">jquery-ui</a></li>
<li><a href="http://grails.org/plugin/blueprint" target="blank">blueprint</a></li>
<li><a href="http://grails.org/plugin/lesscss-resources" target="blank">lesscss-resources</a></li>
<li><a href="http://grails.org/plugin/zipped-resources" target="blank">zipped-resources</a></li>
<li><a href="http://grails.org/plugin/cached-resources" target="blank">cached-resources</a></li>
</ul><p class="paragraph"/>

<a name="6.2.6 Sitemesh Content Blocks"><!-- Legacy link --></a>
<h2 id="sitemeshContentBlocks">7.2.6 Sitemesh Content Blocks</h2>
Although it is useful to decorate an entire page sometimes you may find the need to decorate independent sections of your site. To do this you can use content blocks. To get started, partition the page to be decorated using the <code>&#60;content&#62;</code> tag:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;content tag=<span class="xml&#45;quote">"navbar"</span>&#62;</span>
&#8230; draw the navbar here&#8230;
<span class="xml&#45;tag">&#60;/content&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;content tag=<span class="xml&#45;quote">"header"</span>&#62;</span>
&#8230; draw the header here&#8230;
<span class="xml&#45;tag">&#60;/content&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;content tag=<span class="xml&#45;quote">"footer"</span>&#62;</span>
&#8230; draw the footer here&#8230;
<span class="xml&#45;tag">&#60;/content&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;content tag=<span class="xml&#45;quote">"body"</span>&#62;</span>
&#8230; draw the body here&#8230;
<span class="xml&#45;tag">&#60;/content&#62;</span></pre></div><p class="paragraph"/>Then within the layout you can reference these components and apply individual layouts to each:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;html&#62;</span>
    <span class="xml&#45;tag">&#60;body&#62;</span>
        <span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"header"</span>&#62;</span>
            <span class="xml&#45;tag">&#60;g:applyLayout name=<span class="xml&#45;quote">"headerLayout"</span>&#62;</span>
                <span class="xml&#45;tag">&#60;g:pageProperty name=<span class="xml&#45;quote">"page.header"</span> /&#62;</span>
            <span class="xml&#45;tag">&#60;/g:applyLayout&#62;</span>
        <span class="xml&#45;tag">&#60;/div&#62;</span>
        <span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"nav"</span>&#62;</span>
            <span class="xml&#45;tag">&#60;g:applyLayout name=<span class="xml&#45;quote">"navLayout"</span>&#62;</span>
                <span class="xml&#45;tag">&#60;g:pageProperty name=<span class="xml&#45;quote">"page.navbar"</span> /&#62;</span>
            <span class="xml&#45;tag">&#60;/g:applyLayout&#62;</span>
        <span class="xml&#45;tag">&#60;/div&#62;</span>
        <span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"body"</span>&#62;</span>
            <span class="xml&#45;tag">&#60;g:applyLayout name=<span class="xml&#45;quote">"bodyLayout"</span>&#62;</span>
                <span class="xml&#45;tag">&#60;g:pageProperty name=<span class="xml&#45;quote">"page.body"</span> /&#62;</span>
            <span class="xml&#45;tag">&#60;/g:applyLayout&#62;</span>
        <span class="xml&#45;tag">&#60;/div&#62;</span>
        <span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"footer"</span>&#62;</span>
            <span class="xml&#45;tag">&#60;g:applyLayout name=<span class="xml&#45;quote">"footerLayout"</span>&#62;</span>
                <span class="xml&#45;tag">&#60;g:pageProperty name=<span class="xml&#45;quote">"page.footer"</span> /&#62;</span>
            <span class="xml&#45;tag">&#60;/g:applyLayout&#62;</span>
        <span class="xml&#45;tag">&#60;/div&#62;</span>
    <span class="xml&#45;tag">&#60;/body&#62;</span>
<span class="xml&#45;tag">&#60;/html&#62;</span></pre></div>


<a name="6.2.7 Making Changes to a Deployed Application"><!-- Legacy link --></a>
<h2 id="makingChangesToADeployedApplication">7.2.7 Making Changes to a Deployed Application</h2>
One of the main issues with deploying a Grails application (or typically any servlet-based one) is that any change to the views requires that you redeploy your whole application. If all you want to do is fix a typo on a page, or change an image link, it can seem like a lot of unnecessary work. For such simple requirements, Grails does have a solution: the  <code>grails.gsp.view.dir</code>  configuration setting.<p class="paragraph"/>How does this work? The first step is to decide where the GSP files should go. Let's say we want to keep them unpacked in a  <code>/var/www/grails/my-app</code>  directory. We add these two lines to  <code>grails-app/conf/Config.groovy</code> :
<div class="code"><pre>grails.gsp.enable.reload = <span class="java&#45;keyword">true</span>
grails.gsp.view.dir = <span class="java&#45;quote">"/<span class="java&#45;keyword">var</span>/www/grails/my&#45;app/"</span></pre></div>
The first line tells Grails that modified GSP files should be reloaded at runtime. If you don't have this setting, you can make as many changes as you like but they won't be reflected in the running application until you restart. The second line tells Grails where to load the views and layouts from.<p class="paragraph"/><blockquote class="note">
The trailing slash on the  <code>grails.gsp.view.dir</code>  value is important! Without it, Grails will look for views in the parent directory.
</blockquote><p class="paragraph"/>Setting "grails.gsp.view.dir" is optional. If it's not specified, you can update files directly to the application server's deployed war directory. Depending on the application server, these files might get overwritten when the server is restarted. Most application servers support "exploded war deployment" which is recommended in this case.<p class="paragraph"/>With those settings in place, all you need to do is copy the views from your web application to the external directory. On a Unix-like system, this would look something like this:
<div class="code"><pre>mkdir &#45;p /<span class="java&#45;keyword">var</span>/www/grails/my&#45;app/grails&#45;app/views
cp &#45;R grails&#45;app/views/&#42; /<span class="java&#45;keyword">var</span>/www/grails/my&#45;app/grails&#45;app/views</pre></div>
The key point here is that you must retain the view directory structure, including the  <code>grails-app/views</code>  bit. So you end up with the path  <code>/var/www/grails/my-app/grails-app/views/...</code> .<p class="paragraph"/>One thing to bear in mind with this technique is that every time you modify a GSP, it uses up permgen space. So at some point you will eventually hit "out of permgen space" errors unless you restart the server. So this technique is not recommended for frequent or large changes to the views.<p class="paragraph"/>There are also some System properties to control GSP reloading:
<table class="wiki-table" cellpadding="0" cellspacing="0" border="0"><tr><th><strong class="bold">Name</strong></th><th><strong class="bold">Description</strong></th><th><strong class="bold">Default</strong></th></tr><tr class="table-odd"><td>grails.gsp.enable.reload</td><td>altervative system property for enabling the GSP reload mode without changing Config.groovy</td><td>&#160;</td></tr><tr class="table-even"><td>grails.gsp.reload.interval</td><td>interval between checking the lastmodified time of the gsp source file, unit is milliseconds</td><td>5000</td></tr><tr class="table-odd"><td>grails.gsp.reload.granularity</td><td>the number of milliseconds leeway to give before deciding a file is out of date. this is needed because different roundings usually cause a 1000ms difference in lastmodified times</td><td>1000</td></tr></table><p class="paragraph"/>GSP reloading is supported for precompiled GSPs since Grails 1.3.5 .


<a name="6.2.8 GSP Debugging"><!-- Legacy link --></a>
<h2 id="GSPDebugging">7.2.8 GSP Debugging</h2>
<h4>Viewing the generated source code</h4>
<ul class="star">
<li>Adding "?showSource=true" or "&#38;showSource=true" to the url shows the generated Groovy source code for the view instead of rendering it. It won't show the source code of included templates. This only works in development mode</li>
<li>The saving of all generated source code can be activated by setting the property "grails.views.gsp.keepgenerateddir" (in Config.groovy) . It must point to a directory that exists and is writable.</li>
<li>During "grails war" gsp pre-compilation, the generated source code is stored in grails.project.work.dir/gspcompile (usually in ~/.grails/(grails_version)/projects/(project name)/gspcompile).</li>
</ul><p class="paragraph"/><h4>Debugging GSP code with a debugger</h4>
<ul class="star">
<li>See <a href="http://contraptionsforprogramming.blogspot.com/2010/08/debuggable-gsps-in-springsource-tool.html" target="blank">Debugging GSP in STS</a></li>
</ul><p class="paragraph"/><h4>Viewing information about templates used to render a single url</h4><p class="paragraph"/>GSP templates are reused in large web applications by using the <code>g:render</code> taglib. Several small templates can be used to render a single page.
It might be hard to find out what GSP template actually renders the html seen in the result.
The debug templates -feature adds html comments to the output. The comments contain debug information about gsp templates used to render the page.<p class="paragraph"/>Usage is simple: append "?debugTemplates" or "&#38;debugTemplates" to the url and view the source of the result in your browser.
"debugTemplates" is restricted to development mode. It won't work in production.<p class="paragraph"/>Here is an example of comments added by debugTemplates :
<div class="code"><pre>&#60;!&#45;&#45; GSP &#35;2 START template: /home/.../views/_carousel.gsp
     precompiled: <span class="java&#45;keyword">false</span> lastmodified: &#8230; &#45;&#45;&#62;
.
.
.
&#60;!&#45;&#45; GSP &#35;2 END template: /home/.../views/_carousel.gsp
     rendering time: 115 ms &#45;&#45;&#62;</pre></div><p class="paragraph"/>Each comment block has a unique id so that you can find the start &#38; end of each template call.


<a name="6.3 Tag Libraries"><!-- Legacy link --></a>
<h2 id="taglibs">7.3 Tag Libraries</h2>
Like <a href="http://www.oracle.com/technetwork/java/javaee/jsp/index.html" target="blank">Java Server Pages</a> (JSP), GSP supports the concept of custom tag libraries. Unlike JSP, Grails' tag library mechanism is simple, elegant and completely reloadable at runtime.<p class="paragraph"/>Quite simply, to create a tag library create a Groovy class that ends with the convention <code>TagLib</code> and place it within the <code>grails-app/taglib</code> directory:<p class="paragraph"/><div class="code"><pre>class SimpleTagLib &#123;<p class="paragraph"/>&#125;</pre></div><p class="paragraph"/>Now to create a tag create a Closure property that takes two arguments: the tag attributes and the body content:<p class="paragraph"/><div class="code"><pre>class SimpleTagLib &#123;
    def simple = &#123; attrs, body &#45;&#62;<p class="paragraph"/>    &#125;
&#125;</pre></div><p class="paragraph"/>The <code>attrs</code> argument is a Map of the attributes of the tag, whilst the <code>body</code> argument is a Closure that returns the body content when invoked:<p class="paragraph"/><div class="code"><pre>class SimpleTagLib &#123;
    def emoticon = &#123; attrs, body &#45;&#62;
       out &#60;&#60; body() &#60;&#60; (attrs.happy == '<span class="java&#45;keyword">true</span>' ? <span class="java&#45;quote">" :&#45;)"</span> : <span class="java&#45;quote">" :&#45;("</span>)
    &#125;
&#125;</pre></div><p class="paragraph"/>As demonstrated above there is an implicit <code>out</code> variable that refers to the output <code>Writer</code> which you can use to append content to the response. Then you can reference the tag inside your GSP; no imports are necessary:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:emoticon happy=<span class="xml&#45;quote">"true"</span>&#62;</span>Hi John<span class="xml&#45;tag">&#60;/g:emoticon&#62;</span></pre></div><p class="paragraph"/><blockquote class="note">
To help IDEs like SpringSource Tool Suite (STS) and others autocomplete tag attributes, you should add Javadoc comments to your tag closures with <code>&#64;attr</code> descriptions. Since taglibs use Groovy code it can be difficult to reliably detect all usable attributes.<p class="paragraph"/>For example:<p class="paragraph"/><div class="code"><pre>class SimpleTagLib &#123;<p class="paragraph"/>    /&#42;&#42;
     &#42; Renders the body with an emoticon.
     &#42;
     &#42; @attr happy whether to show a happy emoticon ('<span class="java&#45;keyword">true</span>') or
     &#42; a sad emoticon ('<span class="java&#45;keyword">false</span>')
     &#42;/
    def emoticon = &#123; attrs, body &#45;&#62;
       out &#60;&#60; body() &#60;&#60; (attrs.happy == '<span class="java&#45;keyword">true</span>' ? <span class="java&#45;quote">" :&#45;)"</span> : <span class="java&#45;quote">" :&#45;("</span>)
    &#125;
&#125;</pre></div><p class="paragraph"/>and any mandatory attributes should include the REQUIRED keyword, e.g.<p class="paragraph"/><div class="code"><pre>class SimpleTagLib &#123;<p class="paragraph"/>    /&#42;&#42;
     &#42; Creates a <span class="java&#45;keyword">new</span> password field.
     &#42;
     &#42; @attr name REQUIRED the field name
     &#42; @attr value the field value
     &#42;/
    def passwordField = &#123; attrs &#45;&#62;
        attrs.type = <span class="java&#45;quote">"password"</span>
        attrs.tagName = <span class="java&#45;quote">"passwordField"</span>
        fieldImpl(out, attrs)
    &#125;
&#125;</pre></div>
</blockquote>



<h2 id="taglibVariablesAndScopes">7.3.1 Variables and Scopes</h2>
Within the scope of a tag library there are a number of pre-defined variables including:
<ul class="star">
<li><code>actionName</code> - The currently executing action name</li>
<li><code>controllerName</code> - The currently executing controller name</li>
<li><code>flash</code> - The <a href="../ref/Controllers/flash.html" class="controllers">flash</a> object</li>
<li><code>grailsApplication</code> - The <a href="../api/org/codehaus/groovy/grails/commons/GrailsApplication.html" class="api">GrailsApplication</a> instance</li>
<li><code>out</code> - The response writer for writing to the output stream</li>
<li><code>pageScope</code> - A reference to the <a href="../ref/Tag Libraries/pageScope.html" class="tagLibraries">pageScope</a> object used for GSP rendering (i.e. the binding)</li>
<li><code>params</code> - The <a href="../ref/Controllers/params.html" class="controllers">params</a> object for retrieving request parameters</li>
<li><code>pluginContextPath</code> - The context path to the plugin that contains the tag library</li>
<li><code>request</code> - The <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletRequest.html" class="api">HttpServletRequest</a> instance</li>
<li><code>response</code> - The <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpServletResponse.html" class="api">HttpServletResponse</a> instance</li>
<li><code>servletContext</code> - The <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/ServletContext.html" class="api">javax.servlet.ServletContext</a> instance</li>
<li><code>session</code> - The <a href="http://download.oracle.com/javaee/1.4/api/javax/servlet/http/HttpSession.html" class="api">HttpSession</a> instance</li>
</ul><p class="paragraph"/>

<a name="6.3.2 Simple Tags"><!-- Legacy link --></a>
<h2 id="simpleTags">7.3.2 Simple Tags</h2>
As demonstrated in the previous example it is easy to write simple tags that have no body and just output content. Another example is a <code>dateFormat</code> style tag:<p class="paragraph"/><div class="code"><pre>def dateFormat = &#123; attrs, body &#45;&#62;
    out &#60;&#60; <span class="java&#45;keyword">new</span> java.text.SimpleDateFormat(attrs.format).format(attrs.date)
&#125;</pre></div><p class="paragraph"/>The above uses Java's <code>SimpleDateFormat</code> class to format a date and then write it to the response. The tag can then be used within a GSP as follows:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:dateFormat format=<span class="xml&#45;quote">"dd&#45;MM&#45;yyyy"</span> date=<span class="xml&#45;quote">"$&#123;new Date()&#125;"</span> /&#62;</span></pre></div><p class="paragraph"/>With simple tags sometimes you need to write HTML mark-up to the response. One approach would be to embed the content directly:<p class="paragraph"/><div class="code"><pre>def formatBook = &#123; attrs, body &#45;&#62;
    out &#60;&#60; <span class="java&#45;quote">"&#60;div id=&#34;$&#123;attrs.book.id&#125;&#34;&#62;"</span>
    out &#60;&#60; <span class="java&#45;quote">"Title : $&#123;attrs.book.title&#125;"</span>
    out &#60;&#60; <span class="java&#45;quote">"&#60;/div&#62;"</span>
&#125;</pre></div><p class="paragraph"/>Although this approach may be tempting it is not very clean. A better approach would be to reuse the <a href="../ref/Tags/render.html" class="tags">render</a> tag:<p class="paragraph"/><div class="code"><pre>def formatBook = &#123; attrs, body &#45;&#62;
    out &#60;&#60; render(template: <span class="java&#45;quote">"bookTemplate"</span>, model: &#91;book: attrs.book&#93;)
&#125;</pre></div><p class="paragraph"/>And then have a separate GSP template that does the actual rendering.


<a name="6.3.3 Logical Tags"><!-- Legacy link --></a>
<h2 id="logicalTags">7.3.3 Logical Tags</h2>
You can also create logical tags where the body of the tag is only output once a set of conditions have been met. An example of this may be a set of security tags:<p class="paragraph"/><div class="code"><pre>def isAdmin = &#123; attrs, body &#45;&#62;
    def user = attrs.user
    <span class="java&#45;keyword">if</span> (user &#38;&#38; checkUserPrivs(user)) &#123;
        out &#60;&#60; body()
    &#125;
&#125;</pre></div><p class="paragraph"/>The tag above checks if the user is an administrator and only outputs the body content if he/she has the correct set of access privileges:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:isAdmin user=<span class="xml&#45;quote">"$&#123;myUser&#125;"</span>&#62;</span>
    // some restricted content
<span class="xml&#45;tag">&#60;/g:isAdmin&#62;</span></pre></div>


<a name="6.3.4 Iterative Tags"><!-- Legacy link --></a>
<h2 id="iterativeTags">7.3.4 Iterative Tags</h2>
Iterative tags are easy too, since you can invoke the body multiple times:<p class="paragraph"/><div class="code"><pre>def repeat = &#123; attrs, body &#45;&#62;
    attrs.times?.toInteger()?.times &#123; num &#45;&#62;
        out &#60;&#60; body(num)
    &#125;
&#125;</pre></div><p class="paragraph"/>In this example we check for a <code>times</code> attribute and if it exists convert it to a number, then use Groovy's <code>times</code> method to iterate the specified number of times:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:repeat times=<span class="xml&#45;quote">"3"</span>&#62;</span>
<span class="xml&#45;tag">&#60;p&#62;</span>Repeat this 3 times! Current repeat = $&#123;it&#125;<span class="xml&#45;tag">&#60;/p&#62;</span>
<span class="xml&#45;tag">&#60;/g:repeat&#62;</span></pre></div><p class="paragraph"/>Notice how in this example we use the implicit <code>it</code> variable to refer to the current number. This works because when we invoked the body we passed in the current value inside the iteration:<p class="paragraph"/><div class="code"><pre>out &#60;&#60; body(num)</pre></div><p class="paragraph"/>That value is then passed as the default variable <code>it</code> to the tag. However, if you have nested tags this can lead to conflicts, so you should should instead name the variables that the body uses:<p class="paragraph"/><div class="code"><pre>def repeat = &#123; attrs, body &#45;&#62;
    def <span class="java&#45;keyword">var</span> = attrs.<span class="java&#45;keyword">var</span> ?: <span class="java&#45;quote">"num"</span>
    attrs.times?.toInteger()?.times &#123; num &#45;&#62;
        out &#60;&#60; body((<span class="java&#45;keyword">var</span>):num)
    &#125;
&#125;</pre></div><p class="paragraph"/>Here we check if there is a <code>var</code> attribute and if there is use that as the name to pass into the body invocation on this line:<p class="paragraph"/><div class="code"><pre>out &#60;&#60; body((<span class="java&#45;keyword">var</span>):num)</pre></div><p class="paragraph"/><blockquote class="note">
Note the usage of the parenthesis around the variable name. If you omit these Groovy assumes you are using a String key and not referring to the variable itself.
</blockquote><p class="paragraph"/>Now we can change the usage of the tag as follows:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:repeat times=<span class="xml&#45;quote">"3"</span> var=<span class="xml&#45;quote">"j"</span>&#62;</span>
<span class="xml&#45;tag">&#60;p&#62;</span>Repeat this 3 times! Current repeat = $&#123;j&#125;<span class="xml&#45;tag">&#60;/p&#62;</span>
<span class="xml&#45;tag">&#60;/g:repeat&#62;</span></pre></div><p class="paragraph"/>Notice how we use the <code>var</code> attribute to define the name of the variable <code>j</code> and then we are able to reference that variable within the body of the tag.


<a name="6.3.5 Tag Namespaces"><!-- Legacy link --></a>
<h2 id="namespaces">7.3.5 Tag Namespaces</h2>
By default, tags are added to the default Grails namespace and are used with the <code>g:</code> prefix in GSP pages. However, you can specify a different namespace by adding a static property to your <code>TagLib</code> class:<p class="paragraph"/><div class="code"><pre>class SimpleTagLib &#123;
    <span class="java&#45;keyword">static</span> namespace = <span class="java&#45;quote">"my"</span><p class="paragraph"/>    def example = &#123; attrs &#45;&#62;
        &#8230;
    &#125;
&#125;</pre></div><p class="paragraph"/>Here we have specified a <code>namespace</code> of <code>my</code> and hence the tags in this tag lib must then be referenced from GSP pages like this:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;my:example name=<span class="xml&#45;quote">"..."</span> /&#62;</span></pre></div><p class="paragraph"/>where the prefix is the same as the value of the static <code>namespace</code> property. Namespaces are particularly useful for plugins.<p class="paragraph"/>Tags within namespaces can be invoked as methods using the namespace as a prefix to the method call:<p class="paragraph"/><div class="code"><pre>out &#60;&#60; my.example(name:<span class="java&#45;quote">"foo"</span>)</pre></div><p class="paragraph"/>This works from GSP, controllers or tag libraries


<a name="6.3.6 Using JSP Tag Libraries"><!-- Legacy link --></a>
<h2 id="usingJSPTagLibraries">7.3.6 Using JSP Tag Libraries</h2>
In addition to the simplified tag library mechanism provided by GSP, you can also use JSP tags from GSP. To do so simply declare the JSP to use with the <code>taglib</code> directive:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;%@ taglib prefix=<span class="xml&#45;quote">"fmt"</span> uri=<span class="xml&#45;quote">"http://java.sun.com/jsp/jstl/fmt"</span> %&#62;</span></pre></div><p class="paragraph"/>Then you can use it like any other tag:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;fmt:formatNumber value=<span class="xml&#45;quote">"$&#123;10&#125;"</span> pattern=<span class="xml&#45;quote">".00"</span>/&#62;</span></pre></div><p class="paragraph"/>With the added bonus that you can invoke JSP tags like methods:<p class="paragraph"/><div class="code"><pre>$&#123;fmt.formatNumber(value:10, pattern:<span class="java&#45;quote">".00"</span>)&#125;</pre></div>

<a name="6.3.7 Tag return value"><!-- Legacy link --></a>
<h2 id="tagReturnValue">7.3.7 Tag return value</h2>
Since Grails 1.2, a tag library call returns an instance of <code>org.codehaus.groovy.grails.web.util.StreamCharBuffer</code> class by default.
This change improves performance by reducing object creation and optimizing buffering during request processing.
In earlier Grails versions, a <code>java.lang.String</code> instance was returned.<p class="paragraph"/>Tag libraries can also return direct object values to the caller since Grails 1.2..
Object returning tag names are listed in a static <code>returnObjectForTags</code> property in the tag library class.<p class="paragraph"/>Example:
<div class="code"><pre>class ObjectReturningTagLib &#123;
    <span class="java&#45;keyword">static</span> namespace = <span class="java&#45;quote">"cms"</span>
    <span class="java&#45;keyword">static</span> returnObjectForTags = &#91;'content'&#93;<p class="paragraph"/>    def content = &#123; attrs, body &#45;&#62;
        CmsContent.findByCode(attrs.code)?.content
    &#125;
&#125;</pre></div>

<a name="6.4 URL Mappings"><!-- Legacy link --></a>
<h2 id="urlmappings">7.4 URL Mappings</h2>
Throughout the documentation so far the convention used for URLs has been the default of <code>/controller/action/id</code>. However, this convention is not hard wired into Grails and is in fact controlled by a URL Mappings class located at <code>grails-app/conf/UrlMappings.groovy</code>.<p class="paragraph"/>The <code>UrlMappings</code> class contains a single property called <code>mappings</code> that has been assigned a block of code:<p class="paragraph"/><div class="code"><pre>class UrlMappings &#123;
    <span class="java&#45;keyword">static</span> mappings = &#123;
    &#125;
&#125;</pre></div><p class="paragraph"/>

<a name="6.4.1 Mapping to Controllers and Actions"><!-- Legacy link --></a>
<h2 id="mappingToControllersAndActions">7.4.1 Mapping to Controllers and Actions</h2>
To create a simple mapping simply use a relative URL as the method name and specify named parameters for the controller and action to map to:<p class="paragraph"/><div class="code"><pre><span class="java&#45;quote">"/product"</span>(controller: <span class="java&#45;quote">"product"</span>, action: <span class="java&#45;quote">"list"</span>)</pre></div><p class="paragraph"/>In this case we've mapped the URL <code>/product</code> to the <code>list</code> action of the <code>ProductController</code>. Omit the action definition to map to the default action of the controller:<p class="paragraph"/><div class="code"><pre><span class="java&#45;quote">"/product"</span>(controller: <span class="java&#45;quote">"product"</span>)</pre></div><p class="paragraph"/>An alternative syntax is to assign the controller and action to use within a block passed to the method:<p class="paragraph"/><div class="code"><pre><span class="java&#45;quote">"/product"</span> &#123;
    controller = <span class="java&#45;quote">"product"</span>
    action = <span class="java&#45;quote">"list"</span>
&#125;</pre></div><p class="paragraph"/>Which syntax you use is largely dependent on personal preference. To rewrite one URI onto another explicit URI (rather than a controller/action pair) do something like this:<p class="paragraph"/><div class="code"><pre><span class="java&#45;quote">"/hello"</span>(uri: <span class="java&#45;quote">"/hello.dispatch"</span>)</pre></div><p class="paragraph"/>Rewriting specific URIs is often useful when integrating with other frameworks.


<a name="6.4.2 Embedded Variables"><!-- Legacy link --></a>
<h2 id="embeddedVariables">7.4.2 Embedded Variables</h2>
<h4>Simple Variables</h4><p class="paragraph"/>The previous section demonstrated how to map simple URLs with concrete "tokens". In URL mapping speak tokens are the sequence of characters between each slash, '/'. A concrete token is one which is well defined such as as <code>/product</code>. However, in many circumstances you don't know what the value of a particular token will be until runtime. In this case you can use variable placeholders within the URL for example:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
  <span class="java&#45;quote">"/product/$id"</span>(controller: <span class="java&#45;quote">"product"</span>)
&#125;</pre></div><p class="paragraph"/>In this case by embedding a $id variable as the second token Grails will automatically map the second token into a parameter (available via the <a href="../ref/Controllers/params.html" class="controllers">params</a> object) called <code>id</code>. For example given the URL <code>/product/MacBook</code>, the following code will render "MacBook" to the response:<p class="paragraph"/><div class="code"><pre>class ProductController &#123;
     def index() &#123; render params.id &#125;
&#125;</pre></div><p class="paragraph"/>You can of course construct more complex examples of mappings. For example the traditional blog URL format could be mapped as follows:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
   <span class="java&#45;quote">"/$blog/$year/$month/$day/$id"</span>(controller: <span class="java&#45;quote">"blog"</span>, action: <span class="java&#45;quote">"show"</span>)
&#125;</pre></div><p class="paragraph"/>The above mapping would let you do things like:<p class="paragraph"/><div class="code"><pre>/graemerocher/2007/01/10/my_funky_blog_entry</pre></div><p class="paragraph"/>The individual tokens in the URL would again be mapped into the <a href="../ref/Controllers/params.html" class="controllers">params</a> object with values available for <code>year</code>, <code>month</code>, <code>day</code>, <code>id</code> and so on.<p class="paragraph"/><h4>Dynamic Controller and Action Names</h4><p class="paragraph"/>Variables can also be used to dynamically construct the controller and action name. In fact the default Grails URL mappings use this technique:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    <span class="java&#45;quote">"/$controller/$action?/$id?"</span>()
&#125;</pre></div><p class="paragraph"/>Here the name of the controller, action and id are implicitly obtained from the variables <code>controller</code>, <code>action</code> and <code>id</code> embedded within the URL.<p class="paragraph"/>You can also resolve the controller name and action name to execute dynamically using a closure:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    <span class="java&#45;quote">"/$controller"</span> &#123;
        action = &#123; params.goHere &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/><h4>Optional Variables</h4><p class="paragraph"/>Another characteristic of the default mapping is the ability to append a ? at the end of a variable to make it an optional token. In a further example this technique could be applied to the blog URL mapping to have more flexible linking:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    <span class="java&#45;quote">"/$blog/$year?/$month?/$day?/$id?"</span>(controller:<span class="java&#45;quote">"blog"</span>, action:<span class="java&#45;quote">"show"</span>)
&#125;</pre></div><p class="paragraph"/>With this mapping all of these URLs would match with only the relevant parameters being populated in the <a href="../ref/Controllers/params.html" class="controllers">params</a> object:<p class="paragraph"/><pre class="bq"><code>
/graemerocher/2007/01/10/my_funky_blog_entry
/graemerocher/2007/01/10
/graemerocher/2007/01
/graemerocher/2007
/graemerocher</code></pre><p class="paragraph"/><h4>Arbitrary Variables</h4><p class="paragraph"/>You can also pass arbitrary parameters from the URL mapping into the controller by just setting them in the block passed to the mapping:<p class="paragraph"/><div class="code"><pre><span class="java&#45;quote">"/holiday/win"</span> &#123;
     id = <span class="java&#45;quote">"Marrakech"</span>
     year = 2007
&#125;</pre></div><p class="paragraph"/>This variables will be available within the <a href="../ref/Controllers/params.html" class="controllers">params</a> object passed to the controller.<p class="paragraph"/><h4>Dynamically Resolved Variables</h4><p class="paragraph"/>The hard coded arbitrary variables are useful, but sometimes you need to calculate the name of the variable based on runtime factors. This is also possible by assigning a block to the variable name:<p class="paragraph"/><div class="code"><pre><span class="java&#45;quote">"/holiday/win"</span> &#123;
     id = &#123; params.id &#125;
     isEligible = &#123; session.user != <span class="java&#45;keyword">null</span> &#125; // must be logged in
&#125;</pre></div><p class="paragraph"/>In the above case the code within the blocks is resolved when the URL is actually matched and hence can be used in combination with all sorts of logic.


<a name="6.4.3 Mapping to Views"><!-- Legacy link --></a>
<h2 id="mappingToViews">7.4.3 Mapping to Views</h2>
You can resolve a URL to a view without a controller or action involved. For example to map the root URL <code>/</code> to a GSP at the location <code>grails-app/views/index.gsp</code> you could use:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    <span class="java&#45;quote">"/"</span>(view: <span class="java&#45;quote">"/index"</span>)  // map the root URL
&#125;</pre></div><p class="paragraph"/>Alternatively if you need a view that is specific to a given controller you could use:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
   <span class="java&#45;quote">"/help"</span>(controller: <span class="java&#45;quote">"site"</span>, view: <span class="java&#45;quote">"help"</span>) // to a view <span class="java&#45;keyword">for</span> a controller
&#125;</pre></div>


<a name="6.4.4 Mapping to Response Codes"><!-- Legacy link --></a>
<h2 id="mappingToResponseCodes">7.4.4 Mapping to Response Codes</h2>
Grails also lets you map HTTP response codes to controllers, actions or views. Just use a method name that matches the response code you are interested in:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
   <span class="java&#45;quote">"403"</span>(controller: <span class="java&#45;quote">"errors"</span>, action: <span class="java&#45;quote">"forbidden"</span>)
   <span class="java&#45;quote">"404"</span>(controller: <span class="java&#45;quote">"errors"</span>, action: <span class="java&#45;quote">"notFound"</span>)
   <span class="java&#45;quote">"500"</span>(controller: <span class="java&#45;quote">"errors"</span>, action: <span class="java&#45;quote">"serverError"</span>)
&#125;</pre></div><p class="paragraph"/>Or you can specify custom error pages:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
   <span class="java&#45;quote">"403"</span>(view: <span class="java&#45;quote">"/errors/forbidden"</span>)
   <span class="java&#45;quote">"404"</span>(view: <span class="java&#45;quote">"/errors/notFound"</span>)
   <span class="java&#45;quote">"500"</span>(view: <span class="java&#45;quote">"/errors/serverError"</span>)
&#125;</pre></div><p class="paragraph"/><h4>Declarative Error Handling</h4><p class="paragraph"/>In addition you can configure handlers for individual exceptions:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
   <span class="java&#45;quote">"403"</span>(view: <span class="java&#45;quote">"/errors/forbidden"</span>)
   <span class="java&#45;quote">"404"</span>(view: <span class="java&#45;quote">"/errors/notFound"</span>)
   <span class="java&#45;quote">"500"</span>(controller: <span class="java&#45;quote">"errors"</span>, action: <span class="java&#45;quote">"illegalArgument"</span>,
         exception: IllegalArgumentException)
   <span class="java&#45;quote">"500"</span>(controller: <span class="java&#45;quote">"errors"</span>, action: <span class="java&#45;quote">"nullPointer"</span>,
         exception: NullPointerException)
   <span class="java&#45;quote">"500"</span>(controller: <span class="java&#45;quote">"errors"</span>, action: <span class="java&#45;quote">"customException"</span>,
         exception: MyException)
   <span class="java&#45;quote">"500"</span>(view: <span class="java&#45;quote">"/errors/serverError"</span>)
&#125;</pre></div><p class="paragraph"/>With this configuration, an <code>IllegalArgumentException</code> will be handled by the <code>illegalArgument</code> action in <code>ErrorsController</code>, a <code>NullPointerException</code> will be handled by the <code>nullPointer</code> action, and a <code>MyException</code> will be handled by the <code>customException</code> action. Other exceptions will be handled by the catch-all rule and use the <code>/errors/serverError</code> view.<p class="paragraph"/>You can access the exception from your custom error handing view or controller action using the request's <code>exception</code> attribute like so:<p class="paragraph"/><div class="code"><pre>class ErrorController &#123;
    def handleError() &#123;
        def exception = request.exception
        // perform desired processing to handle the exception
    &#125;
&#125;</pre></div><p class="paragraph"/><blockquote class="warning">
If your error-handling controller action throws an exception as well, you'll end up with a <code>StackOverflowException</code>.
</blockquote>


<a name="6.4.5 Mapping to HTTP methods"><!-- Legacy link --></a>
<h2 id="mappingHTTP">7.4.5 Mapping to HTTP methods</h2>
URL mappings can also be configured to map based on the HTTP method (GET, POST, PUT or DELETE). This is very useful for RESTful APIs and for restricting mappings based on HTTP method.<p class="paragraph"/>As an example the following mappings provide a RESTful API URL mappings for the <code>ProductController</code>:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
   <span class="java&#45;quote">"/product/$id"</span>(controller:<span class="java&#45;quote">"product"</span>) &#123;
       action = &#91;GET:<span class="java&#45;quote">"show"</span>, PUT:<span class="java&#45;quote">"update"</span>, DELETE:<span class="java&#45;quote">"delete"</span>, POST:<span class="java&#45;quote">"save"</span>&#93;
   &#125;
&#125;</pre></div>

<a name="6.4.6 Mapping Wildcards"><!-- Legacy link --></a>
<h2 id="mappingWildcards">7.4.6 Mapping Wildcards</h2>
Grails' URL mappings mechanism also supports wildcard mappings. For example consider the following mapping:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    <span class="java&#45;quote">"/images/&#42;.jpg"</span>(controller: <span class="java&#45;quote">"image"</span>)
&#125;</pre></div><p class="paragraph"/>This mapping will match all paths to images such as <code>/image/logo.jpg</code>. Of course you can achieve the same effect with a variable:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    <span class="java&#45;quote">"/images/$name.jpg"</span>(controller: <span class="java&#45;quote">"image"</span>)
&#125;</pre></div><p class="paragraph"/>However, you can also use double wildcards to match more than one level below:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    <span class="java&#45;quote">"/images/&#42;&#42;.jpg"</span>(controller: <span class="java&#45;quote">"image"</span>)
&#125;</pre></div><p class="paragraph"/>In this cases the mapping will match <code>/image/logo.jpg</code> as well as <code>/image/other/logo.jpg</code>. Even better you can use a double wildcard variable:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    // will match /image/logo.jpg and /image/other/logo.jpg
    <span class="java&#45;quote">"/images/$name&#42;&#42;.jpg"</span>(controller: <span class="java&#45;quote">"image"</span>)
&#125;</pre></div><p class="paragraph"/>In this case it will store the path matched by the wildcard inside a <code>name</code> parameter obtainable from the <a href="../ref/Controllers/params.html" class="controllers">params</a> object:<p class="paragraph"/><div class="code"><pre>def name = params.name
println name // prints <span class="java&#45;quote">"logo"</span> or <span class="java&#45;quote">"other/logo"</span></pre></div><p class="paragraph"/>If you use wildcard URL mappings then you may want to exclude certain URIs from Grails' URL mapping process. To do this you can provide an <code>excludes</code> setting inside the <code>UrlMappings.groovy</code> class:<p class="paragraph"/><div class="code"><pre>class UrlMappings &#123;
    <span class="java&#45;keyword">static</span> excludes = &#91;<span class="java&#45;quote">"/images/&#42;"</span>, <span class="java&#45;quote">"/css/&#42;"</span>&#93;
    <span class="java&#45;keyword">static</span> mappings = &#123;
        &#8230;
    &#125;
&#125;</pre></div><p class="paragraph"/>In this case Grails won't attempt to match any URIs that start with <code>/images</code> or <code>/css</code>.


<a name="6.4.7 Automatic Link Re-Writing"><!-- Legacy link --></a>
<h2 id="automaticLinkRewriting">7.4.7 Automatic Link Re-Writing</h2>
Another great feature of URL mappings is that they automatically customize the behaviour of the <a href="../ref/Tags/link.html" class="tags">link</a> tag so that changing the mappings don't require you to go and change all of your links.<p class="paragraph"/>This is done through a URL re-writing technique that reverse engineers the links from the URL mappings. So given a mapping such as the blog one from an earlier section:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
   <span class="java&#45;quote">"/$blog/$year?/$month?/$day?/$id?"</span>(controller:<span class="java&#45;quote">"blog"</span>, action:<span class="java&#45;quote">"show"</span>)
&#125;</pre></div><p class="paragraph"/>If you use the link tag as follows:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:link controller=<span class="xml&#45;quote">"blog"</span> action=<span class="xml&#45;quote">"show"</span>
        params=<span class="xml&#45;quote">"&#91;blog:'fred', year:2007&#93;"</span>&#62;</span>
    My Blog
<span class="xml&#45;tag">&#60;/g:link&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;g:link controller=<span class="xml&#45;quote">"blog"</span> action=<span class="xml&#45;quote">"show"</span>
        params=<span class="xml&#45;quote">"&#91;blog:'fred', year:2007, month:10&#93;"</span>&#62;</span>
    My Blog &#45; October 2007 Posts
<span class="xml&#45;tag">&#60;/g:link&#62;</span></pre></div><p class="paragraph"/>Grails will automatically re-write the URL in the correct format:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;a href=<span class="xml&#45;quote">"/fred/2007"</span>&#62;</span>My Blog<span class="xml&#45;tag">&#60;/a&#62;</span>
<span class="xml&#45;tag">&#60;a href=<span class="xml&#45;quote">"/fred/2007/10"</span>&#62;</span>My Blog &#45; October 2007 Posts<span class="xml&#45;tag">&#60;/a&#62;</span></pre></div>


<a name="6.4.8 Applying Constraints"><!-- Legacy link --></a>
<h2 id="applyingConstraints">7.4.8 Applying Constraints</h2>
URL Mappings also support Grails' unified <a href="../guide/single.html#constraints" class="guide">validation constraints</a> mechanism, which lets you further "constrain" how a URL is matched. For example, if we revisit the blog sample code from earlier, the mapping currently looks like this:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
   <span class="java&#45;quote">"/$blog/$year?/$month?/$day?/$id?"</span>(controller:<span class="java&#45;quote">"blog"</span>, action:<span class="java&#45;quote">"show"</span>)
&#125;</pre></div><p class="paragraph"/>This allows URLs such as:<p class="paragraph"/><div class="code"><pre>/graemerocher/2007/01/10/my_funky_blog_entry</pre></div><p class="paragraph"/>However, it would also allow:<p class="paragraph"/><div class="code"><pre>/graemerocher/not_a_year/not_a_month/not_a_day/my_funky_blog_entry</pre></div><p class="paragraph"/>This is problematic as it forces you to do some clever parsing in the controller code. Luckily, URL Mappings can be constrained to further validate the URL tokens:<p class="paragraph"/><div class="code"><pre><span class="java&#45;quote">"/$blog/$year?/$month?/$day?/$id?"</span> &#123;
     controller = <span class="java&#45;quote">"blog"</span>
     action = <span class="java&#45;quote">"show"</span>
     constraints &#123;
          year(matches:/&#92;d&#123;4&#125;/)
          month(matches:/&#92;d&#123;2&#125;/)
          day(matches:/&#92;d&#123;2&#125;/)
     &#125;
&#125;</pre></div><p class="paragraph"/>In this case the constraints ensure that the <code>year</code>, <code>month</code> and <code>day</code> parameters match a particular valid pattern thus relieving you of that burden later on.

<a name="6.4.9 Named URL Mappings"><!-- Legacy link --></a>
<h2 id="namedMappings">7.4.9 Named URL Mappings</h2>
URL Mappings also support named mappings, that is mappings which have a name associated with them. The name may be used to refer to a specific mapping when links are generated.<p class="paragraph"/>The syntax for defining a named mapping is as follows:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
   name &#60;mapping name&#62;: &#60;url pattern&#62; &#123;
      // &#8230;
   &#125;
&#125;</pre></div><p class="paragraph"/>For example:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    name personList: <span class="java&#45;quote">"/showPeople"</span> &#123;
        controller = 'person'
        action = 'list'
    &#125;
    name accountDetails: <span class="java&#45;quote">"/details/$acctNumber"</span> &#123;
        controller = 'product'
        action = 'accountDetails'
    &#125;
&#125;</pre></div><p class="paragraph"/>The mapping may be referenced in a link tag in a GSP.<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:link mapping=<span class="xml&#45;quote">"personList"</span>&#62;</span>List People<span class="xml&#45;tag">&#60;/g:link&#62;</span></pre></div><p class="paragraph"/>That would result in:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;a href=<span class="xml&#45;quote">"/showPeople"</span>&#62;</span>List People<span class="xml&#45;tag">&#60;/a&#62;</span></pre></div><p class="paragraph"/>Parameters may be specified using the params attribute.<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:link mapping=<span class="xml&#45;quote">"accountDetails"</span> params=<span class="xml&#45;quote">"&#91;acctNumber:'8675309'&#93;"</span>&#62;</span>
    Show Account
<span class="xml&#45;tag">&#60;/g:link&#62;</span></pre></div><p class="paragraph"/>That would result in:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;a href=<span class="xml&#45;quote">"/details/8675309"</span>&#62;</span>Show Account<span class="xml&#45;tag">&#60;/a&#62;</span></pre></div><p class="paragraph"/>Alternatively you may reference a named mapping using the link namespace.<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;link:personList&#62;</span>List People<span class="xml&#45;tag">&#60;/link:personList&#62;</span></pre></div><p class="paragraph"/>That would result in:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;a href=<span class="xml&#45;quote">"/showPeople"</span>&#62;</span>List People<span class="xml&#45;tag">&#60;/a&#62;</span></pre></div><p class="paragraph"/>The link namespace approach allows parameters to be specified as attributes.<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;link:accountDetails acctNumber=<span class="xml&#45;quote">"8675309"</span>&#62;</span>Show Account<span class="xml&#45;tag">&#60;/link:accountDetails&#62;</span></pre></div><p class="paragraph"/>That would result in:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;a href=<span class="xml&#45;quote">"/details/8675309"</span>&#62;</span>Show Account<span class="xml&#45;tag">&#60;/a&#62;</span></pre></div><p class="paragraph"/>To specify attributes that should be applied to the generated <code>href</code>, specify a <code>Map</code> value to the <code>attrs</code> attribute.  These attributes will be applied directly to the href, not passed through to be used as request parameters.<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;link:accountDetails attrs=<span class="xml&#45;quote">"&#91;class: 'fancy'&#93;"</span> acctNumber=<span class="xml&#45;quote">"8675309"</span>&#62;</span>
    Show Account
<span class="xml&#45;tag">&#60;/link:accountDetails&#62;</span></pre></div><p class="paragraph"/>That would result in:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;a href=<span class="xml&#45;quote">"/details/8675309"</span> class=<span class="xml&#45;quote">"fancy"</span>&#62;</span>Show Account<span class="xml&#45;tag">&#60;/a&#62;</span></pre></div>



<h2 id="customizingUrlFormat">7.4.10 Customizing URL Formats</h2>
The default URL Mapping mechanism supports camel case names in the URLs.  The default URL for accessing an action named <code>addNumbers</code> in a controller named <code>MathHelperController</code> would be something like <code>/mathHelper/addNumbers</code>.  Grails allows for the customization of this pattern and provides an implementation which replaces the camel case convention with a hyphenated convention that would support URLs like <code>/math-helper/add-numbers</code>.  To enable hyphenated URLs assign a value of "hyphenated" to the <code>grails.web.url.converter</code> property in <code>grails-app/conf/Config.groovy</code>.<p class="paragraph"/><div class="code"><pre>// grails&#45;app/conf/Config.groovy<p class="paragraph"/>grails.web.url.converter = 'hyphenated'</pre></div><p class="paragraph"/>Arbitrary strategies may be plugged in by providing a class which implements the <a href="../api/grails/web/UrlConverter.html" class="api">UrlConverter</a> interface and adding an instance of that class to the Spring application context with the bean name of <code>grails.web.UrlConverter.BEAN_NAME</code>.  If Grails finds a bean in the context with that name, it will be used as the default converter and there is no need to assign a value to the <code>grails.web.url.converter</code> config property.<p class="paragraph"/><div class="code"><pre>// src/groovy/com/myapplication/MyUrlConverterImpl.groovy<p class="paragraph"/><span class="java&#45;keyword">package</span> com.myapplication<p class="paragraph"/>class MyUrlConverterImpl <span class="java&#45;keyword">implements</span> grails.web.UrlConverter &#123;<p class="paragraph"/>    <span class="java&#45;object">String</span> toUrlElement(<span class="java&#45;object">String</span> propertyOrClassName) &#123;
        // <span class="java&#45;keyword">return</span> some representation of a property or class name that should be used in URLs&#8230;
    &#125;
&#125;</pre></div><p class="paragraph"/><div class="code"><pre>// grails&#45;app/conf/spring/resources.groovy<p class="paragraph"/>beans = &#123;
    <span class="java&#45;quote">"$&#123;grails.web.UrlConverter.BEAN_NAME&#125;"</span>(com.myapplication.MyUrlConverterImpl)
&#125;</pre></div>



<h2 id="namespacedControllers">7.4.11 Namespaced Controllers</h2>
An application is not allowed to define multiple controllers with the same
name, even if they are defined in separate packages.  For example an
application may not contain <code>com.accounting.ReportingController</code> and
<code>com.humanresources.ReportingController</code>.  However it is allowed for
an application to use a plugin which provides a controller with the
same name as a controller provided by the application as long as the
controllers are in separate packages.  For example, an application
may include a controller named <code>com.accounting.ReportingController</code>
and the application may use a plugin which provides a controller
named <code>com.humanresources.ReportingController</code>.  The only issue
with that is the URL mapping for the controller provided by the
plugin needs to be explicit in specifying that the mapping applies
to the <code>ReportingController</code> which is provided by the plugin.<p class="paragraph"/>See the following example.<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    <span class="java&#45;quote">"/accountingReports"</span> &#123;
        controller = <span class="java&#45;quote">"reporting"</span>
    &#125;
    <span class="java&#45;quote">"/humanResourceReports"</span> &#123;
        controller = <span class="java&#45;quote">"reporting"</span>
        plugin = <span class="java&#45;quote">"humanResources"</span>
    &#125;
&#125;</pre></div><p class="paragraph"/>With that mapping in place, a request to <code>/accountingReports</code> will
be handled by the <code>ReportingController</code> which is defined in the
application.  A request to <code>/humanResourceReports</code> will be handled
by the <code>ReportingController</code> which is provided by the <code>humanResources</code>
plugin.<p class="paragraph"/>There could be any number of <code>ReportingController</code> controllers provided
by any number of plugins but no plugin may provide more than one
<code>ReportingController</code> even if they are defined in separate packages.<p class="paragraph"/>Assigning a value to the <code>plugin</code> variable in the mapping is only
required if there are multiple controllers with the same name
available at runtime provided by the application and/or plugins.
If the <code>humanResources</code> plugin provides a <code>ReportingController</code> and
there is no other <code>ReportingController</code> available at runtime, the
following mapping would work.<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">static</span> mappings = &#123;
    <span class="java&#45;quote">"/humanResourceReports"</span> &#123;
        controller = <span class="java&#45;quote">"reporting"</span>
    &#125;
&#125;</pre></div><p class="paragraph"/>It is best practice to be explicit about the fact that the controller
is being provided by a plugin though.<p class="paragraph"/>


<a name="6.5 Web Flow"><!-- Legacy link --></a>
<h2 id="webflow">7.5 Web Flow</h2>
<h4>Overview</h4><p class="paragraph"/>Grails supports the creation of web flows built on the <a href="http://www.springsource.org/webflow" target="blank">Spring Web Flow</a> project. A web flow is a conversation that spans multiple requests and retains state for the scope of the flow. A web flow also has a defined start and end state.<p class="paragraph"/>Web flows don't require an HTTP session, but instead store their state in a serialized form, which is then restored using a flow execution key that Grails passes around as a request parameter. This makes flows far more scalable than other forms of stateful application that use the HttpSession and its inherit memory and clustering concerns.<p class="paragraph"/>Web flow is essentially an advanced state machine that manages the "flow" of execution from one state to the next. Since the state is managed for you, you don't have to be concerned with ensuring that users enter an action in the middle of some multi step flow, as web flow manages that for you. This makes web flow perfect for use cases such as shopping carts, hotel booking and any application that has multi page work flows.<p class="paragraph"/><blockquote class="note">
From Grails 1.2 onwards Webflow is no longer in Grails core, so you must install the Webflow plugin to use this feature: <code>grails install-plugin webflow</code>
</blockquote><p class="paragraph"/><h4>Creating a Flow</h4><p class="paragraph"/>To create a flow create a regular Grails controller and add an action that ends with the convention <code>Flow</code>. For example:<p class="paragraph"/><div class="code"><pre>class BookController &#123;<p class="paragraph"/>   def index() &#123;
      redirect(action: <span class="java&#45;quote">"shoppingCart"</span>)
   &#125;<p class="paragraph"/>   def shoppingCartFlow = &#123;
        &#8230;
   &#125;
&#125;</pre></div><p class="paragraph"/>Notice when redirecting or referring to the flow as an action we omit the <code>Flow</code> suffix. In other words the name of the action of the above flow is <code>shoppingCart</code>.


<a name="6.5.1 Start and End States"><!-- Legacy link --></a>
<h2 id="startAndEndStates">7.5.1 Start and End States</h2>
As mentioned before a flow has a defined start and end state. A start state is the state which is entered when a user first initiates a conversation (or flow). The start state of a Grails flow is the first method call that takes a block. For example:<p class="paragraph"/><div class="code"><pre>class BookController &#123;
   &#8230;
   def shoppingCartFlow =&#123;
       showCart &#123;
           on(<span class="java&#45;quote">"checkout"</span>).to <span class="java&#45;quote">"enterPersonalDetails"</span>
           on(<span class="java&#45;quote">"continueShopping"</span>).to <span class="java&#45;quote">"displayCatalogue"</span>
       &#125;
       &#8230;
       displayCatalogue &#123;
           redirect(controller: <span class="java&#45;quote">"catalogue"</span>, action: <span class="java&#45;quote">"show"</span>)
       &#125;
       displayInvoice()
   &#125;
&#125;</pre></div><p class="paragraph"/>Here the <code>showCart</code> node is the start state of the flow. Since the showCart state doesn't define an action or redirect it is assumed be a <a href="../guide/single.html#actionStatesAndViewStates" class="guide">view state</a> that, by convention, refers to the view  <code>grails-app/views/book/shoppingCart/showCart.gsp</code>.<p class="paragraph"/>Notice that unlike regular controller actions, the views are stored within a directory that matches the name of the flow: <code>grails-app/views/book/shoppingCart</code>.<p class="paragraph"/>The <code>shoppingCart</code> flow also has two possible end states. The first is <code>displayCatalogue</code> which performs an external redirect to another controller and action, thus exiting the flow. The second is <code>displayInvoice</code> which is an end state as it has no events at all and will simply render a view called <code>grails-app/views/book/shoppingCart/displayInvoice.gsp</code> whilst ending the flow at the same time.<p class="paragraph"/>Once a flow has ended it can only be resumed from the start state, in this case <code>showCart</code>, and not from any other state.


<a name="6.5.2 Action States and View States"><!-- Legacy link --></a>
<h2 id="actionStatesAndViewStates">7.5.2 Action States and View States</h2>
<h4>View states</h4><p class="paragraph"/>A view state is a one that doesn't define an <code>action</code> or a <code>redirect</code>. So for example this is a view state:<p class="paragraph"/><div class="code"><pre>enterPersonalDetails &#123;
   on(<span class="java&#45;quote">"submit"</span>).to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"<span class="java&#45;keyword">return</span>"</span>).to <span class="java&#45;quote">"showCart"</span>
&#125;</pre></div><p class="paragraph"/>It will look for a view called <code>grails-app/views/book/shoppingCart/enterPersonalDetails.gsp</code> by default. Note that the <code>enterPersonalDetails</code> state defines two events: <code>submit</code> and <code>return</code>. The view is responsible for <a href="../guide/single.html#flowExecutionEvents" class="guide">triggering</a> these events. Use the <code>render</code> method to change the view to be rendered:<p class="paragraph"/><div class="code"><pre>enterPersonalDetails &#123;
   render(view: <span class="java&#45;quote">"enterDetailsView"</span>)
   on(<span class="java&#45;quote">"submit"</span>).to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"<span class="java&#45;keyword">return</span>"</span>).to <span class="java&#45;quote">"showCart"</span>
&#125;</pre></div><p class="paragraph"/>Now it will look for <code>grails-app/views/book/shoppingCart/enterDetailsView.gsp</code>. Start the <code>view</code> parameter with a / to use a shared view:<p class="paragraph"/><div class="code"><pre>enterPersonalDetails &#123;
   render(view: <span class="java&#45;quote">"/shared/enterDetailsView"</span>)
   on(<span class="java&#45;quote">"submit"</span>).to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"<span class="java&#45;keyword">return</span>"</span>).to <span class="java&#45;quote">"showCart"</span>
&#125;</pre></div><p class="paragraph"/>Now it will look for <code>grails-app/views/shared/enterDetailsView.gsp</code><p class="paragraph"/><h4>Action States</h4><p class="paragraph"/>An action state is a state that executes code but does not render a view. The result of the action is used to dictate flow transition. To create an action state you define an action to to be executed. This is done by calling the <code>action</code> method and passing it a block of code to be executed:<p class="paragraph"/><div class="code"><pre>listBooks &#123;
   action &#123;
      &#91;bookList: Book.list()&#93;
   &#125;
   on(<span class="java&#45;quote">"success"</span>).to <span class="java&#45;quote">"showCatalogue"</span>
   on(Exception).to <span class="java&#45;quote">"handleError"</span>
&#125;</pre></div><p class="paragraph"/>As you can see an action looks very similar to a controller action and in fact you can reuse controller actions if you want. If the action successfully returns with no errors the <code>success</code> event will be triggered. In this case since we return a Map, which is regarded as the "model" and is automatically placed in <a href="../guide/single.html#flowScopes" class="guide">flow scope</a>.<p class="paragraph"/>In addition, in the above example we also use an exception handler to deal with errors on the line:<p class="paragraph"/><div class="code"><pre>on(Exception).to <span class="java&#45;quote">"handleError"</span></pre></div><p class="paragraph"/>This makes the flow transition to a state called <code>handleError</code> in the case of an exception.<p class="paragraph"/>You can write more complex actions that interact with the flow request context:<p class="paragraph"/><div class="code"><pre>processPurchaseOrder &#123;
    action &#123;
        def a =  flow.address
        def p = flow.person
        def pd = flow.paymentDetails
        def cartItems = flow.cartItems
        flow.clear()<p class="paragraph"/>        def o = <span class="java&#45;keyword">new</span> Order(person: p, shippingAddress: a, paymentDetails: pd)
        o.invoiceNumber = <span class="java&#45;keyword">new</span> Random().nextInt(9999999)
        <span class="java&#45;keyword">for</span> (item in cartItems) &#123; o.addToItems item &#125;
        o.save()
        &#91;order: o&#93;
    &#125;
    on(<span class="java&#45;quote">"error"</span>).to <span class="java&#45;quote">"confirmPurchase"</span>
    on(Exception).to <span class="java&#45;quote">"confirmPurchase"</span>
    on(<span class="java&#45;quote">"success"</span>).to <span class="java&#45;quote">"displayInvoice"</span>
&#125;</pre></div><p class="paragraph"/>Here is a more complex action that gathers all the information accumulated from the flow scope and creates an <code>Order</code> object. It then returns the order as the model. The important thing to note here is the interaction with the request context and "flow scope".<p class="paragraph"/><h4>Transition Actions</h4><p class="paragraph"/>Another form of action is what is known as a  <em class="italic">transition</em>  action. A transition action is executed directly prior to state transition once an <a href="../guide/single.html#flowExecutionEvents" class="guide">event</a> has been triggered. A simple example of a transition action can be seen below:<p class="paragraph"/><div class="code"><pre>enterPersonalDetails &#123;
   on(<span class="java&#45;quote">"submit"</span>) &#123;
       log.trace <span class="java&#45;quote">"Going to enter shipping"</span>
   &#125;.to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"<span class="java&#45;keyword">return</span>"</span>).to <span class="java&#45;quote">"showCart"</span>
&#125;</pre></div><p class="paragraph"/>Notice how we pass a block of the code to <code>submit</code> event that simply logs the transition. Transition states are very useful for <a href="../guide/single.html#dataBindingAndValidation" class="guide">data binding and validation</a>, which is covered in a later section.


<a name="6.5.3 Flow Execution Events"><!-- Legacy link --></a>
<h2 id="flowExecutionEvents">7.5.3 Flow Execution Events</h2>
In order to  <em class="italic">transition</em>  execution of a flow from one state to the next you need some way of trigger an  <em class="italic">event</em>  that indicates what the flow should do next. Events can be triggered from either view states or action states.<p class="paragraph"/><h4>Triggering Events from a View State</h4><p class="paragraph"/>As discussed previously the start state of the flow in a previous code listing deals with two possible events. A <code>checkout</code> event and a <code>continueShopping</code> event:<p class="paragraph"/><div class="code"><pre>def shoppingCartFlow = &#123;
    showCart &#123;
        on(<span class="java&#45;quote">"checkout"</span>).to <span class="java&#45;quote">"enterPersonalDetails"</span>
        on(<span class="java&#45;quote">"continueShopping"</span>).to <span class="java&#45;quote">"displayCatalogue"</span>
    &#125;
    &#8230;
&#125;</pre></div><p class="paragraph"/>Since the <code>showCart</code> event is a view state it will render the view <code>grails-app/book/shoppingCart/showCart.gsp</code>. Within this view you need to have components that trigger flow execution. On a form this can be done use the <a href="../ref/Tags/submitButton.html" class="tags">submitButton</a> tag:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:form&#62;</span>
    <span class="xml&#45;tag">&#60;g:submitButton name=<span class="xml&#45;quote">"continueShopping"</span> value=<span class="xml&#45;quote">"Continue Shopping"</span> /&#62;</span>
    <span class="xml&#45;tag">&#60;g:submitButton name=<span class="xml&#45;quote">"checkout"</span> value=<span class="xml&#45;quote">"Checkout"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;/g:form&#62;</span></pre></div><p class="paragraph"/>The form automatically submits back to the <code>shoppingCart</code> flow. The name attribute of each <a href="../ref/Tags/submitButton.html" class="tags">submitButton</a> tag signals which event will be triggered. If you don't have a form you can also trigger an event with the <a href="../ref/Tags/link.html" class="tags">link</a> tag as follows:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:link event=<span class="xml&#45;quote">"checkout"</span> /&#62;</span></pre></div><p class="paragraph"/><blockquote class="note">
Prior to 2.0.0, it was required to specify the controller and/or action in forms and links, which caused the url to change when entering a subflow state. When the controller and action are not specified,
all url's are relative to the main flow execution url, which makes your flows reusable as subflows and prevents issues with the browser's back button.
</blockquote><p class="paragraph"/><h4>Triggering Events from an Action</h4><p class="paragraph"/>To trigger an event from an <code>action</code> you invoke a method. For example there is the built in <code>error()</code> and <code>success()</code> methods. The example below triggers the <code>error()</code> event on validation failure in a transition action:<p class="paragraph"/><div class="code"><pre>enterPersonalDetails &#123;
   on(<span class="java&#45;quote">"submit"</span>) &#123;
         def p = <span class="java&#45;keyword">new</span> Person(params)
         flow.person = p
         <span class="java&#45;keyword">if</span> (!p.validate()) <span class="java&#45;keyword">return</span> error()
   &#125;.to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"<span class="java&#45;keyword">return</span>"</span>).to <span class="java&#45;quote">"showCart"</span>
&#125;</pre></div><p class="paragraph"/>In this case because of the error the transition action will make the flow go back to the <code>enterPersonalDetails</code> state.<p class="paragraph"/>With an action state you can also trigger events to redirect flow:<p class="paragraph"/><div class="code"><pre>shippingNeeded &#123;
   action &#123;
       <span class="java&#45;keyword">if</span> (params.shippingRequired) yes()
       <span class="java&#45;keyword">else</span> no()
   &#125;
   on(<span class="java&#45;quote">"yes"</span>).to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"no"</span>).to <span class="java&#45;quote">"enterPayment"</span>
&#125;</pre></div><p class="paragraph"/>

<a name="6.5.4 Flow Scopes"><!-- Legacy link --></a>
<h2 id="flowScopes">7.5.4 Flow Scopes</h2>
<h4>Scope Basics</h4><p class="paragraph"/>You'll notice from previous examples that we used a special object called <code>flow</code> to store objects within "flow scope". Grails flows have five different scopes you can utilize:
<ul class="star">
<li><code>request</code> - Stores an object for the scope of the current request</li>
<li><code>flash</code> - Stores the object for the current and next request only</li>
<li><code>flow</code> - Stores objects for the scope of the flow, removing them when the flow reaches an end state</li>
<li><code>conversation</code> - Stores objects for the scope of the conversation including the root flow and nested subflows</li>
<li><code>session</code> - Stores objects in the user's session</li>
</ul><p class="paragraph"/><blockquote class="note">
Grails service classes can be automatically scoped to a web flow scope. See the documentation on <a href="../guide/single.html#services" class="guide">Services</a> for more information.
</blockquote><p class="paragraph"/>Returning a model Map from an action will automatically result in the model being placed in flow scope. For example, using a transition action, you can place objects within <code>flow</code> scope as follows:<p class="paragraph"/><div class="code"><pre>enterPersonalDetails &#123;
    on(<span class="java&#45;quote">"submit"</span>) &#123;
        &#91;person: <span class="java&#45;keyword">new</span> Person(params)&#93;
    &#125;.to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"<span class="java&#45;keyword">return</span>"</span>).to <span class="java&#45;quote">"showCart"</span>
&#125;</pre></div><p class="paragraph"/>Be aware that a new request is always created for each state, so an object placed in request scope in an action state (for example) will not be available in a subsequent view state. Use one of the other scopes to pass objects from one state to another. Also note that Web Flow:
<ol>
<li>Moves objects from flash scope to request scope upon transition between states;</li>
<li>Merges objects from the flow and conversation scopes into the view model before rendering (so you shouldn't include a scope prefix when referencing these objects within a view, e.g. GSP pages).</li>
</ol><p class="paragraph"/><h4>Flow Scopes and Serialization</h4><p class="paragraph"/>When placing objects in <code>flash</code>, <code>flow</code> or <code>conversation</code> scope they must implement <code>java.io.Serializable</code> or an exception will be thrown. This has an impact on <a href="../guide/single.html#GORM" class="guide">domain classes</a> in that domain classes are typically placed within a scope so that they can be rendered in a view. For example consider the following domain class:<p class="paragraph"/><div class="code"><pre>class Book &#123;
    <span class="java&#45;object">String</span> title
&#125;</pre></div><p class="paragraph"/>To place an instance of the <code>Book</code> class in a flow scope you will need to modify it as follows:<p class="paragraph"/><div class="code"><pre>class Book <span class="java&#45;keyword">implements</span> Serializable &#123;
    <span class="java&#45;object">String</span> title
&#125;</pre></div><p class="paragraph"/>This also impacts associations and closures you declare within a domain class. For example consider this:<p class="paragraph"/><div class="code"><pre>class Book <span class="java&#45;keyword">implements</span> Serializable &#123;
    <span class="java&#45;object">String</span> title
    Author author
&#125;</pre></div><p class="paragraph"/>Here if the <code>Author</code> association is not <code>Serializable</code> you will also get an error. This also impacts closures used in <a href="../guide/single.html#eventsAutoTimestamping" class="guide">GORM events</a> such as <code>onLoad</code>, <code>onSave</code> and so on. The following domain class will cause an error if an instance is placed in a flow scope:<p class="paragraph"/><div class="code"><pre>class Book <span class="java&#45;keyword">implements</span> Serializable &#123;<p class="paragraph"/>    <span class="java&#45;object">String</span> title<p class="paragraph"/>    def onLoad = &#123;
        println <span class="java&#45;quote">"I'm loading"</span>
    &#125;
&#125;</pre></div><p class="paragraph"/>The reason is that the assigned block on the <code>onLoad</code> event cannot be serialized. To get around this you should declare all events as <code>transient</code>:<p class="paragraph"/><div class="code"><pre>class Book <span class="java&#45;keyword">implements</span> Serializable &#123;<p class="paragraph"/>    <span class="java&#45;object">String</span> title<p class="paragraph"/>    <span class="java&#45;keyword">transient</span> onLoad = &#123;
        println <span class="java&#45;quote">"I'm loading"</span>
    &#125;
&#125;</pre></div><p class="paragraph"/>or as methods:<p class="paragraph"/><div class="code"><pre>class Book <span class="java&#45;keyword">implements</span> Serializable &#123;<p class="paragraph"/>    <span class="java&#45;object">String</span> title<p class="paragraph"/>    def onLoad() &#123;
        println <span class="java&#45;quote">"I'm loading"</span>
    &#125;
&#125;</pre></div><p class="paragraph"/><blockquote class="note">
The flow scope contains a reference to the Hibernate session. As a result, any object loaded into the session through a GORM query will also be in the flow and will need to implement Serializable.<p class="paragraph"/>If you don't want your domain class to be Serializable or stored in the flow, then you will need to evict the entity manually before the end of the state:<p class="paragraph"/><div class="code"><pre>flow.persistenceContext.evict(it)</pre></div>
</blockquote>


<a name="6.5.5 Data Binding and Validation"><!-- Legacy link --></a>
<h2 id="dataBindingAndValidation">7.5.5 Data Binding and Validation</h2>
In the section on <a href="../guide/single.html#startAndEndStates" class="guide">start and end states</a>, the start state in the first example triggered a transition to the <code>enterPersonalDetails</code> state. This state renders a view and waits for the user to enter the required information:<p class="paragraph"/><div class="code"><pre>enterPersonalDetails &#123;
   on(<span class="java&#45;quote">"submit"</span>).to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"<span class="java&#45;keyword">return</span>"</span>).to <span class="java&#45;quote">"showCart"</span>
&#125;</pre></div><p class="paragraph"/>The view contains a form with two submit buttons that either trigger the submit event or the return event:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:form&#62;</span>
    <span class="xml&#45;comment">&#60;!&#45;&#45; Other fields &#45;&#45;&#62;</span>
    <span class="xml&#45;tag">&#60;g:submitButton name=<span class="xml&#45;quote">"submit"</span> value=<span class="xml&#45;quote">"Continue"</span>&#62;</span><span class="xml&#45;tag">&#60;/g:submitButton&#62;</span>
    <span class="xml&#45;tag">&#60;g:submitButton name=<span class="xml&#45;quote">"return"</span> value=<span class="xml&#45;quote">"Back"</span>&#62;</span><span class="xml&#45;tag">&#60;/g:submitButton&#62;</span>
<span class="xml&#45;tag">&#60;/g:form&#62;</span></pre></div><p class="paragraph"/>However, what about the capturing the information submitted by the form? To capture the form info we can use a flow transition action:<p class="paragraph"/><div class="code"><pre>enterPersonalDetails &#123;
   on(<span class="java&#45;quote">"submit"</span>) &#123;
      flow.person = <span class="java&#45;keyword">new</span> Person(params)
      !flow.person.validate() ? error() : success()
   &#125;.to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"<span class="java&#45;keyword">return</span>"</span>).to <span class="java&#45;quote">"showCart"</span>
&#125;</pre></div><p class="paragraph"/>Notice how we perform data binding from request parameters and place the <code>Person</code> instance within <code>flow</code> scope. Also interesting is that we perform <a href="../guide/single.html#validation" class="guide">validation</a> and invoke the <code>error()</code> method if validation fails. This signals to the flow that the transition should halt and return to the <code>enterPersonalDetails</code> view so valid entries can be entered by the user, otherwise the transition should continue and go to the <code>enterShipping</code> state.<p class="paragraph"/>Like regular actions, flow actions also support the notion of <a href="../guide/single.html#commandObjects" class="guide">Command Objects</a> by defining the first argument of the closure:<p class="paragraph"/><div class="code"><pre>enterPersonalDetails &#123;
   on(<span class="java&#45;quote">"submit"</span>) &#123; PersonDetailsCommand cmd &#45;&#62;
       flow.personDetails = cmd
      !flow.personDetails.validate() ? error() : success()
   &#125;.to <span class="java&#45;quote">"enterShipping"</span>
   on(<span class="java&#45;quote">"<span class="java&#45;keyword">return</span>"</span>).to <span class="java&#45;quote">"showCart"</span>
&#125;</pre></div>


<a name="6.5.6 Subflows and Conversations"><!-- Legacy link --></a>
<h2 id="subflowsAndConversations">7.5.6 Subflows and Conversations</h2>
<h4>Calling subflows</h4>
Grails' Web Flow integration also supports subflows. A subflow is like a flow within a flow. For example take this search flow:<p class="paragraph"/><div class="code"><pre>def searchFlow = &#123;
    displaySearchForm &#123;
        on(<span class="java&#45;quote">"submit"</span>).to <span class="java&#45;quote">"executeSearch"</span>
    &#125;
    executeSearch &#123;
        action &#123;
            &#91;results:searchService.executeSearch(params.q)&#93;
        &#125;
        on(<span class="java&#45;quote">"success"</span>).to <span class="java&#45;quote">"displayResults"</span>
        on(<span class="java&#45;quote">"error"</span>).to <span class="java&#45;quote">"displaySearchForm"</span>
    &#125;
    displayResults &#123;
        on(<span class="java&#45;quote">"searchDeeper"</span>).to <span class="java&#45;quote">"extendedSearch"</span>
        on(<span class="java&#45;quote">"searchAgain"</span>).to <span class="java&#45;quote">"displaySearchForm"</span>
    &#125;
    extendedSearch &#123;
        // Extended search subflow
        subflow(controller: <span class="java&#45;quote">"searchExtensions"</span>, action: <span class="java&#45;quote">"extendedSearch"</span>)
        on(<span class="java&#45;quote">"moreResults"</span>).to <span class="java&#45;quote">"displayMoreResults"</span>
        on(<span class="java&#45;quote">"noResults"</span>).to <span class="java&#45;quote">"displayNoMoreResults"</span>
    &#125;
    displayMoreResults()
    displayNoMoreResults()
&#125;</pre></div><p class="paragraph"/>It references a subflow in the <code>extendedSearch</code> state. The controller parameter is optional if the subflow is defined in the same controller as the calling flow.
<blockquote class="note">
Prior to 1.3.5, the previous subflow call would look like <code>subflow(new SearchExtensionsController().extendedSearchFlow)</code>, with the requirement that the name of the subflow state be the same as the called subflow (minus <code>Flow</code>). This way of calling a subflow is deprecated and only supported for backward compatibility.
</blockquote><p class="paragraph"/>The subflow is another flow entirely:<p class="paragraph"/><div class="code"><pre>def extendedSearchFlow = &#123;
    startExtendedSearch &#123;
        on(<span class="java&#45;quote">"findMore"</span>).to <span class="java&#45;quote">"searchMore"</span>
        on(<span class="java&#45;quote">"searchAgain"</span>).to <span class="java&#45;quote">"noResults"</span>
    &#125;
    searchMore &#123;
        action &#123;
           def results = searchService.deepSearch(ctx.conversation.query)
           <span class="java&#45;keyword">if</span> (!results) <span class="java&#45;keyword">return</span> error()
           conversation.extendedResults = results
        &#125;
        on(<span class="java&#45;quote">"success"</span>).to <span class="java&#45;quote">"moreResults"</span>
        on(<span class="java&#45;quote">"error"</span>).to <span class="java&#45;quote">"noResults"</span>
    &#125;
    moreResults()
    noResults()
&#125;</pre></div><p class="paragraph"/>Notice how it places the <code>extendedResults</code> in conversation scope. This scope differs to flow scope as it lets you share state that spans the whole conversation, i.e. a flow execution including all subflows, not just the flow itself. Also notice that the end state (either <code>moreResults</code> or <code>noResults</code> of the subflow triggers the events in the main flow:<p class="paragraph"/><div class="code"><pre>extendedSearch &#123;
    // Extended search subflow
    subflow(controller: <span class="java&#45;quote">"searchExtensions"</span>, action: <span class="java&#45;quote">"extendedSearch"</span>)
    on(<span class="java&#45;quote">"moreResults"</span>).to <span class="java&#45;quote">"displayMoreResults"</span>
    on(<span class="java&#45;quote">"noResults"</span>).to <span class="java&#45;quote">"displayNoMoreResults"</span>
&#125;</pre></div><p class="paragraph"/><h4>Subflow input and output</h4>
Using conversation scope for passing input and output between flows can be compared with using global variables to pass information between methods.
While this is OK in certain situations, it is usually better to use method arguments and return values. In webflow speak, this means defining input and output arguments for flows.<p class="paragraph"/>Consider following flow for searching a person with a certain expertise:<p class="paragraph"/><div class="code"><pre>def searchFlow = &#123;
        input &#123;
            expertise(required: <span class="java&#45;keyword">true</span>)
            title(<span class="java&#45;quote">"Search person"</span>)
        &#125;<p class="paragraph"/>        search &#123;
            onEntry &#123;
                &#91;personInstanceList: Person.findAllByExpertise(flow.expertise)&#93;
            &#125;
            on(<span class="java&#45;quote">"select"</span>) &#123;
                flow.person = Person.get(params.id)
            &#125;.to(<span class="java&#45;quote">"selected"</span>)
            on(<span class="java&#45;quote">"cancel"</span>).to(<span class="java&#45;quote">"cancel"</span>)
        &#125;<p class="paragraph"/>        selected &#123;
            output &#123;
                person &#123;flow.person&#125;
            &#125;
        &#125;
        cancel()
    &#125;<p class="paragraph"/>&#125;</pre></div><p class="paragraph"/>This flow accepts two input parameters:
<ul class="star">
<li>a required expertise argument</li>
<li>an optional title argument with a default value</li>
</ul><p class="paragraph"/>All input arguments are stored in flow scope and are, just like local variables, only visible within this flow.<p class="paragraph"/>A flow that contains required input will throw an exception when an execution is started without providing the input. The consequence is that these flows can only be started as subflows.<p class="paragraph"/>Notice how an end state can define one or more named output values. If the value is a closure, this closure will be evaluated at the end of each flow execution.
If the value is not a closure, the value will be a constant that is only calculated once at flow definition time.<p class="paragraph"/>When a subflow is called, we can provide it a map with input values:<p class="paragraph"/><div class="code"><pre>def newProjectWizardFlow = &#123;
    ...<p class="paragraph"/>    managerSearch &#123;
        subflow(controller: <span class="java&#45;quote">"person"</span>, action: <span class="java&#45;quote">"search"</span>,
                input: &#91;expertise : <span class="java&#45;quote">"management"</span>, title: <span class="java&#45;quote">"Search project manager"</span>&#93;)
        on(<span class="java&#45;quote">"selected"</span>) &#123;
            flow.projectInstance.manager = currentEvent.attributes.person
        &#125;.to <span class="java&#45;quote">"techleadSearch"</span>
    &#125;<p class="paragraph"/>    techleadSearch &#123;
        subflow(controller: <span class="java&#45;quote">"person"</span>, action: <span class="java&#45;quote">"search"</span>,
                input: &#91;expertise : &#123; flow.technology &#125;, title: <span class="java&#45;quote">"Search technical lead"</span>&#93;)
        on(<span class="java&#45;quote">"selected"</span>) &#123;
            flow.projectInstance.techlead = currentEvent.attributes.person
        &#125;.to <span class="java&#45;quote">"projectDetails"</span>
    &#125;<p class="paragraph"/>    ...<p class="paragraph"/>&#125;</pre></div><p class="paragraph"/>Notice again the difference between constant values like <code>expertise : "management"</code> and dynamic values like <code>expertise : { flow.technology }</code><p class="paragraph"/>The subflow output is available via <code>currentEvent.attributes</code>


<a name="6.6 Filters"><!-- Legacy link --></a>
<h2 id="filters">7.6 Filters</h2>
Although Grails <a href="../guide/single.html#controllers" class="guide">controllers</a> support fine grained interceptors, these are only really useful when applied to a few controllers and become difficult to manage with larger applications. Filters on the other hand can be applied across a whole group of controllers, a URI space or to a specific action. Filters are far easier to plugin and maintain completely separately to your main controller logic and are useful for all sorts of cross cutting concerns such as security, logging, and so on.


<a name="6.6.1 Applying Filters"><!-- Legacy link --></a>
<h2 id="applyingFilters">7.6.1 Applying Filters</h2>
To create a filter create a class that ends with the convention <code>Filters</code> in the <code>grails-app/conf</code> directory. Within this class define a code block called <code>filters</code> that contains the filter definitions:<p class="paragraph"/><div class="code"><pre>class ExampleFilters &#123;
   def filters = &#123;
        // your filters here
   &#125;
&#125;</pre></div><p class="paragraph"/>Each filter you define within the <code>filters</code> block has a name and a scope. The name is the method name and the scope is defined using named arguments. For example to define a filter that applies to all controllers and all actions you can use wildcards:<p class="paragraph"/><div class="code"><pre>sampleFilter(controller:'&#42;', action:'&#42;') &#123;
  // interceptor definitions
&#125;</pre></div><p class="paragraph"/>The scope of the filter can be one of the following things:
<ul class="star">
<li>A controller and/or action name pairing with optional wildcards</li>
<li>A URI, with Ant path matching syntax</li>
</ul><p class="paragraph"/>Filter rule attributes:
<ul class="star">
<li><code>controller</code> - controller matching pattern, by default &#42; is replaced with .&#42; and a regex is compiled</li>
<li><code>controllerExclude</code> - controller exclusion pattern, by default &#42; is replaced with .&#42; and a regex is compiled</li>
<li><code>action</code> - action matching pattern, by default &#42; is replaced with .&#42; and a regex is compiled</li>
<li><code>actionExclude</code> - action exclusion pattern, by default &#42; is replaced with .&#42; and a regex is compiled</li>
<li><code>regex</code> (<code>true</code>/<code>false</code>) - use regex syntax (don't replace '&#42;' with '.&#42;')</li>
<li><code>uri</code> - a uri to match, expressed with as Ant style path (e.g. /book/&#42;&#42;)</li>
<li><code>uriExclude</code> - a uri pattern to exclude, expressed with as Ant style path (e.g. /book/&#42;&#42;)</li>
<li><code>find</code> (<code>true</code>/<code>false</code>) - rule matches with partial match (see <code>java.util.regex.Matcher.find()</code>)</li>
<li><code>invert</code> (<code>true</code>/<code>false</code>) - invert the rule (NOT rule)</li>
</ul><p class="paragraph"/>Some examples of filters include:
<ul class="star">
<li>All controllers and actions</li>
</ul><p class="paragraph"/><div class="code"><pre>all(controller: '&#42;', action: '&#42;') &#123;<p class="paragraph"/>&#125;</pre></div>
<ul class="star">
<li>Only for the <code>BookController</code></li>
</ul><p class="paragraph"/><div class="code"><pre>justBook(controller: 'book', action: '&#42;') &#123;<p class="paragraph"/>&#125;</pre></div>
<ul class="star">
<li>All controllers except the <code>BookController</code></li>
</ul><p class="paragraph"/><div class="code"><pre>notBook(controller: 'book', invert: <span class="java&#45;keyword">true</span>) &#123;<p class="paragraph"/>&#125;</pre></div>
<ul class="star">
<li>All actions containing 'save' in the action name</li>
</ul><p class="paragraph"/><div class="code"><pre>saveInActionName(action: '&#42;save&#42;', find: <span class="java&#45;keyword">true</span>) &#123;<p class="paragraph"/>&#125;</pre></div>
<ul class="star">
<li>All actions starting with the letter 'b' except for actions beginning with the phrase 'bad*'</li>
</ul><p class="paragraph"/><div class="code"><pre>actionBeginningWithBButNotBad(action: 'b&#42;', actionExclude: 'bad&#42;', find: <span class="java&#45;keyword">true</span>) &#123;<p class="paragraph"/>&#125;</pre></div>
<ul class="star">
<li>Applied to a URI space</li>
</ul><p class="paragraph"/><div class="code"><pre>someURIs(uri: '/book/&#42;&#42;') &#123;<p class="paragraph"/>&#125;</pre></div>
<ul class="star">
<li>Applied to all URIs</li>
</ul><p class="paragraph"/><div class="code"><pre>allURIs(uri: '/&#42;&#42;') &#123;<p class="paragraph"/>&#125;</pre></div><p class="paragraph"/>In addition, the order in which you define the filters within the <code>filters</code> code block dictates the order in which they are executed.  To control the order of execution between <code>Filters</code> classes, you can use the <code>dependsOn</code> property discussed in <a href="../guide/single.html#filterDependencies" class="guide">filter dependencies</a> section.<p class="paragraph"/><blockquote class="note">
Note: When exclude patterns are used they take precedence over the matching patterns.  For example, if action is 'b&#42;' and actionExclude is 'bad&#42;' then actions like 'best' and 'bien' will have that filter applied but actions like 'bad' and 'badlands' will not.
</blockquote>


<a name="6.6.2 Filter Types"><!-- Legacy link --></a>
<h2 id="filterTypes">7.6.2 Filter Types</h2>
Within the body of the filter you can then define one or several of the following interceptor types for the filter:
<ul class="star">
<li><code>before</code> - Executed before the action. Return <code>false</code> to indicate that the response has been handled that that all future filters and the action should not execute</li>
<li><code>after</code> - Executed after an action. Takes a first argument as the view model to allow modification of the model before rendering the view</li>
<li><code>afterView</code> - Executed after view rendering.  Takes an Exception as an argument which will be non-<code>null</code> if an exception occurs during processing. Note: this Closure is called before the layout is applied.</li>
</ul><p class="paragraph"/>For example to fulfill the common simplistic authentication use case you could define a filter as follows:<p class="paragraph"/><div class="code"><pre>class SecurityFilters &#123;
   def filters = &#123;
       loginCheck(controller: '&#42;', action: '&#42;') &#123;
           before = &#123;
              <span class="java&#45;keyword">if</span> (!session.user &#38;&#38; !actionName.equals('login')) &#123;
                  redirect(action: 'login')
                  <span class="java&#45;keyword">return</span> <span class="java&#45;keyword">false</span>
               &#125;
           &#125;
       &#125;
   &#125;
&#125;</pre></div><p class="paragraph"/>Here the <code>loginCheck</code> filter uses a <code>before</code> interceptor to execute a block of code that checks if a user is in the session and if not redirects to the login action. Note how returning false ensure that the action itself is not executed.<p class="paragraph"/>Here's a more involved example that demonstrates all three filter types:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">import</span> java.util.concurrent.atomic.AtomicLong<p class="paragraph"/>class LoggingFilters &#123;<p class="paragraph"/>   <span class="java&#45;keyword">private</span> <span class="java&#45;keyword">static</span> <span class="java&#45;keyword">final</span> AtomicLong REQUEST_NUMBER_COUNTER = <span class="java&#45;keyword">new</span> AtomicLong()
   <span class="java&#45;keyword">private</span> <span class="java&#45;keyword">static</span> <span class="java&#45;keyword">final</span> <span class="java&#45;object">String</span> START_TIME_ATTRIBUTE = 'Controller__START_TIME__'
   <span class="java&#45;keyword">private</span> <span class="java&#45;keyword">static</span> <span class="java&#45;keyword">final</span> <span class="java&#45;object">String</span> REQUEST_NUMBER_ATTRIBUTE = 'Controller__REQUEST_NUMBER__'<p class="paragraph"/>   def filters = &#123;<p class="paragraph"/>      logFilter(controller: '&#42;', action: '&#42;') &#123;<p class="paragraph"/>         before = &#123;
            <span class="java&#45;keyword">if</span> (!log.debugEnabled) <span class="java&#45;keyword">return</span> <span class="java&#45;keyword">true</span><p class="paragraph"/>            <span class="java&#45;object">long</span> start = <span class="java&#45;object">System</span>.currentTimeMillis()
            <span class="java&#45;object">long</span> currentRequestNumber = REQUEST_NUMBER_COUNTER.incrementAndGet()<p class="paragraph"/>            request&#91;START_TIME_ATTRIBUTE&#93; = start
            request&#91;REQUEST_NUMBER_ATTRIBUTE&#93; = currentRequestNumber<p class="paragraph"/>            log.debug <span class="java&#45;quote">"preHandle request &#35;&#36;currentRequestNumber : "</span> +
               <span class="java&#45;quote">"'&#36;request.servletPath'/'&#36;request.forwardURI', "</span> +
               <span class="java&#45;quote">"from &#36;request.remoteHost (&#36;request.remoteAddr) "</span> +
               <span class="java&#45;quote">" at &#36;&#123;<span class="java&#45;keyword">new</span> Date()&#125;, Ajax: &#36;request.xhr, controller: &#36;controllerName, "</span> +
               <span class="java&#45;quote">"action: &#36;actionName, params: &#36;&#123;<span class="java&#45;keyword">new</span> TreeMap(params)&#125;"</span><p class="paragraph"/>            <span class="java&#45;keyword">return</span> <span class="java&#45;keyword">true</span>
         &#125;<p class="paragraph"/>         after = &#123; Map model &#45;&#62;<p class="paragraph"/>            <span class="java&#45;keyword">if</span> (!log.debugEnabled) <span class="java&#45;keyword">return</span> <span class="java&#45;keyword">true</span><p class="paragraph"/>            <span class="java&#45;object">long</span> start = request&#91;START_TIME_ATTRIBUTE&#93;
            <span class="java&#45;object">long</span> end = <span class="java&#45;object">System</span>.currentTimeMillis()
            <span class="java&#45;object">long</span> requestNumber = request&#91;REQUEST_NUMBER_ATTRIBUTE&#93;<p class="paragraph"/>            def msg = <span class="java&#45;quote">"postHandle request &#35;&#36;requestNumber: end &#36;&#123;<span class="java&#45;keyword">new</span> Date()&#125;, "</span> +
                      <span class="java&#45;quote">"controller total time &#36;&#123;end &#45; start&#125;ms"</span>
            <span class="java&#45;keyword">if</span> (log.traceEnabled) &#123;
            	log.trace msg + <span class="java&#45;quote">"; model: &#36;model"</span>
            &#125;
            <span class="java&#45;keyword">else</span> &#123;
            	log.debug msg
            &#125;
         &#125;<p class="paragraph"/>         afterView = &#123; Exception e &#45;&#62;<p class="paragraph"/>            <span class="java&#45;keyword">if</span> (!log.debugEnabled) <span class="java&#45;keyword">return</span> <span class="java&#45;keyword">true</span><p class="paragraph"/>            <span class="java&#45;object">long</span> start = request&#91;START_TIME_ATTRIBUTE&#93;
            <span class="java&#45;object">long</span> end = <span class="java&#45;object">System</span>.currentTimeMillis()
            <span class="java&#45;object">long</span> requestNumber = request&#91;REQUEST_NUMBER_ATTRIBUTE&#93;<p class="paragraph"/>            def msg = <span class="java&#45;quote">"afterCompletion request &#35;&#36;requestNumber: "</span> +
                      <span class="java&#45;quote">"end &#36;&#123;<span class="java&#45;keyword">new</span> Date()&#125;, total time &#36;&#123;end &#45; start&#125;ms"</span>
            <span class="java&#45;keyword">if</span> (e) &#123;
               log.debug <span class="java&#45;quote">"&#36;msg &#92;n&#92;texception: &#36;e.message"</span>, e
            &#125;
            <span class="java&#45;keyword">else</span> &#123;
               log.debug msg
            &#125;
         &#125;
      &#125;
   &#125;
&#125;</pre></div><p class="paragraph"/>In this logging example we just log various request information, but note that the <code>model</code> map in the <code>after</code> filter is mutable. If you need to add or remove items from the model map you can do that in the <code>after</code> filter.



<h2 id="filterVariablesAndScopes">7.6.3 Variables and Scopes</h2>
Filters support all the common properties available to <a href="../guide/single.html#controllers" class="guide">controllers</a> and <a href="../guide/single.html#taglibs" class="guide">tag libraries</a>, plus the application context:
<ul class="star">
<li><a href="../ref/Controllers/request.html" class="controllers">request</a> - The HttpServletRequest object</li>
<li><a href="../ref/Controllers/response.html" class="controllers">response</a> - The HttpServletResponse object</li>
<li><a href="../ref/Controllers/session.html" class="controllers">session</a> - The HttpSession object</li>
<li><a href="../ref/Controllers/servletContext.html" class="controllers">servletContext</a> - The ServletContext object</li>
<li><a href="../ref/Controllers/flash.html" class="controllers">flash</a> - The flash object</li>
<li><a href="../ref/Controllers/params.html" class="controllers">params</a> - The request parameters object</li>
<li><a href="../ref/Controllers/actionName.html" class="controllers">actionName</a> - The action name that is being dispatched to</li>
<li><a href="../ref/Controllers/controllerName.html" class="controllers">controllerName</a> - The controller name that is being dispatched to</li>
<li><a href="../ref/Controllers/grailsApplication.html" class="controllers">grailsApplication</a> - The Grails application currently running</li>
<li><a href="http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/context/ApplicationContext.html" class="api">applicationContext</a> - The ApplicationContext object</li>
</ul><p class="paragraph"/>However, filters only support a subset of the methods available to controllers and tag libraries. These include:
<ul class="star">
<li><a href="../ref/Controllers/redirect.html" class="controllers">redirect</a> - For redirects to other controllers and actions</li>
<li><a href="../ref/Controllers/render.html" class="controllers">render</a> - For rendering custom responses</li>
</ul><p class="paragraph"/>

<a name="6.6.4 Filter Dependencies"><!-- Legacy link --></a>
<h2 id="filterDependencies">7.6.4 Filter Dependencies</h2>
In a <code>Filters</code> class, you can specify any other <code>Filters</code> classes that should first be executed using the <code>dependsOn</code> property. This is used when a <code>Filters</code> class depends on the behavior of another <code>Filters</code> class (e.g. setting up the environment, modifying the request/session, etc.) and is defined as an array of <code>Filters</code> classes.<p class="paragraph"/>Take the following example <code>Filters</code> classes:<p class="paragraph"/><div class="code"><pre>class MyFilters &#123;
    def dependsOn = &#91;MyOtherFilters&#93;<p class="paragraph"/>    def filters = &#123;
        checkAwesome(uri: <span class="java&#45;quote">"/&#42;"</span>) &#123;
            before = &#123;
                <span class="java&#45;keyword">if</span> (request.isAwesome) &#123; // <span class="java&#45;keyword">do</span> something awesome &#125;
            &#125;
        &#125;<p class="paragraph"/>        checkAwesome2(uri: <span class="java&#45;quote">"/&#42;"</span>) &#123;
            before = &#123;
                <span class="java&#45;keyword">if</span> (request.isAwesome) &#123; // <span class="java&#45;keyword">do</span> something <span class="java&#45;keyword">else</span> awesome &#125;
            &#125;
        &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/><div class="code"><pre>class MyOtherFilters &#123;
    def filters = &#123;
        makeAwesome(uri: <span class="java&#45;quote">"/&#42;"</span>) &#123;
            before = &#123;
                request.isAwesome = <span class="java&#45;keyword">true</span>
            &#125;
        &#125;
        doNothing(uri: <span class="java&#45;quote">"/&#42;"</span>) &#123;
            before = &#123;
                // <span class="java&#45;keyword">do</span> nothing
            &#125;
        &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/>MyFilters specifically <code>dependsOn</code> MyOtherFilters.  This will cause all the filters in MyOtherFilters whose scope matches the current request to be executed before those in MyFilters. For a request of "/test", which will match the scope of every filter in the example, the execution order would be as follows:
<ul class="star">
<li>MyOtherFilters - makeAwesome</li>
<li>MyOtherFilters - doNothing</li>
<li>MyFilters - checkAwesome</li>
<li>MyFilters - checkAwesome2</li>
</ul><p class="paragraph"/>The filters within the MyOtherFilters class are processed in order first, followed by the filters in the MyFilters class.  Execution order between <code>Filters</code> classes are enabled and the execution order of filters within each <code>Filters</code> class are preserved.<p class="paragraph"/>If any cyclical dependencies are detected, the filters with cyclical dependencies will be added to the end of the filter chain and processing will continue.  Information about any cyclical dependencies that are detected will be written to the logs.  Ensure that your root logging level is set to at least WARN or configure an appender for the Grails Filters Plugin (<code>org.codehaus.groovy.grails.plugins.web.filters.FiltersGrailsPlugin</code>) when debugging filter dependency issues.


<a name="6.7 Ajax"><!-- Legacy link --></a>
<h2 id="ajax">7.7 Ajax</h2>
Ajax is the driving force behind the shift to richer web applications. These types of applications in general are better suited to agile, dynamic frameworks written in languages like <a href="http://groovy.codehaus.org" target="blank">Groovy</a> and <a href="http://www.ruby-lang.org/." target="blank">Ruby</a> Grails provides support for building Ajax applications through its Ajax tag library. For a full list of these see the Tag Library Reference.


<a name="6.7.1 Ajax Support"><!-- Legacy link --></a>
<h2 id="ajaxSupport">7.7.1 Ajax Support</h2>
By default Grails ships with the <a href="http://jquery.com/" target="blank">jQuery</a> library, but through the <a href="../guide/single.html#plugins" class="guide">Plugin system</a> provides support for other frameworks such as <a href="http://www.prototypejs.org/" target="blank">Prototype</a>, Dojo:http://dojotoolkit.org/, Yahoo UI:http://developer.yahoo.com/yui/ and the <a href="http://code.google.com/webtoolkit/" target="blank">Google Web Toolkit</a>.<p class="paragraph"/>This section covers Grails' support for Ajax in general. To get started, add this line to the <code>&#60;head&#62;</code> tag of your page:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:javascript library=<span class="xml&#45;quote">"jquery"</span> /&#62;</span></pre></div><p class="paragraph"/>You can replace <code>jQuery</code> with any other library supplied by a plugin you have installed. This works because of Grails' support for adaptive tag libraries. Thanks to Grails' plugin system there is support for a number of different Ajax libraries including (but not limited to):
<ul class="star">
<li>jQuery</li>
<li>Prototype</li>
<li>Dojo</li>
<li>YUI</li>
<li>MooTools</li>
</ul><p class="paragraph"/>

<a name="6.7.1.1 Remoting Linking"><!-- Legacy link --></a>
<h2 id="remotingLinking">7.7.1.1 Remoting Linking</h2>
Remote content can be loaded in a number of ways, the most commons way is through the <a href="../ref/Tags/remoteLink.html" class="tags">remoteLink</a> tag. This tag allows the creation of HTML anchor tags that perform an asynchronous request and optionally set the response in an element. The simplest way to create a remote link is as follows:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:remoteLink action=<span class="xml&#45;quote">"delete"</span> id=<span class="xml&#45;quote">"1"</span>&#62;</span>Delete Book<span class="xml&#45;tag">&#60;/g:remoteLink&#62;</span></pre></div><p class="paragraph"/>The above link sends an asynchronous request to the <code>delete</code> action of the current controller with an id of <code>1</code>.


<a name="6.7.1.2 Updating Content"><!-- Legacy link --></a>
<h2 id="updatingContent">7.7.1.2 Updating Content</h2>
This is great, but usually you provide feedback to the user about what happened:<p class="paragraph"/><div class="code"><pre>def delete() &#123;
    def b = Book.get(params.id)
    b.delete()
    render <span class="java&#45;quote">"Book $&#123;b.id&#125; was deleted"</span>
&#125;</pre></div><p class="paragraph"/>GSP code:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"message"</span>&#62;</span><span class="xml&#45;tag">&#60;/div&#62;</span>
<span class="xml&#45;tag">&#60;g:remoteLink action=<span class="xml&#45;quote">"delete"</span> id=<span class="xml&#45;quote">"1"</span> update=<span class="xml&#45;quote">"message"</span>&#62;</span>
Delete Book
<span class="xml&#45;tag">&#60;/g:remoteLink&#62;</span></pre></div><p class="paragraph"/>The above example will call the action and set the contents of the <code>message</code> <code>div</code> to the response in this case <code>"Book 1 was deleted"</code>. This is done by the <code>update</code> attribute on the tag, which can also take a Map to indicate what should be updated on failure:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"message"</span>&#62;</span><span class="xml&#45;tag">&#60;/div&#62;</span>
<span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"error"</span>&#62;</span><span class="xml&#45;tag">&#60;/div&#62;</span>
<span class="xml&#45;tag">&#60;g:remoteLink update=<span class="xml&#45;quote">"&#91;success: 'message', failure: 'error'&#93;"</span>
              action=<span class="xml&#45;quote">"delete"</span> id=<span class="xml&#45;quote">"1"</span>&#62;</span>
Delete Book
<span class="xml&#45;tag">&#60;/g:remoteLink&#62;</span></pre></div><p class="paragraph"/>Here the <code>error</code> div will be updated if the request failed.


<a name="6.7.1.3 Remote Form Submission"><!-- Legacy link --></a>
<h2 id="remoteFormSubmission">7.7.1.3 Remote Form Submission</h2>
An HTML form can also be submitted asynchronously in one of two ways. Firstly using the <a href="../ref/Tags/formRemote.html" class="tags">formRemote</a> tag which expects similar attributes to those for the <a href="../ref/Tags/remoteLink.html" class="tags">remoteLink</a> tag:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:formRemote url=<span class="xml&#45;quote">"&#91;controller: 'book', action: 'delete'&#93;"</span>
              update=<span class="xml&#45;quote">"&#91;success: 'message', failure: 'error'&#93;"</span>&#62;</span>
    <span class="xml&#45;tag">&#60;input type=<span class="xml&#45;quote">"hidden"</span> name=<span class="xml&#45;quote">"id"</span> value=<span class="xml&#45;quote">"1"</span> /&#62;</span>
    <span class="xml&#45;tag">&#60;input type=<span class="xml&#45;quote">"submit"</span> value=<span class="xml&#45;quote">"Delete Book!"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;/g:formRemote &#62;</span></pre></div><p class="paragraph"/>Or alternatively you can use the <a href="../ref/Tags/submitToRemote.html" class="tags">submitToRemote</a> tag to create a submit button. This allows some buttons to submit remotely and some not depending on the action:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;form action=<span class="xml&#45;quote">"delete"</span>&#62;</span>
    <span class="xml&#45;tag">&#60;input type=<span class="xml&#45;quote">"hidden"</span> name=<span class="xml&#45;quote">"id"</span> value=<span class="xml&#45;quote">"1"</span> /&#62;</span>
    <span class="xml&#45;tag">&#60;g:submitToRemote action=<span class="xml&#45;quote">"delete"</span>
                      update=<span class="xml&#45;quote">"&#91;success: 'message', failure: 'error'&#93;"</span> /&#62;</span>
<span class="xml&#45;tag">&#60;/form&#62;</span></pre></div><p class="paragraph"/>

<a name="6.7.1.4 Ajax Events"><!-- Legacy link --></a>
<h2 id="ajaxEvents">7.7.1.4 Ajax Events</h2>
Specific JavaScript can be called if certain events occur, all the events start with the "on" prefix and let you give feedback to the user where appropriate, or take other action:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:remoteLink action=<span class="xml&#45;quote">"show"</span>
              id=<span class="xml&#45;quote">"1"</span>
              update=<span class="xml&#45;quote">"success"</span>
              onLoading=<span class="xml&#45;quote">"showProgress()"</span>
              onComplete=<span class="xml&#45;quote">"hideProgress()"</span>&#62;</span>Show Book 1<span class="xml&#45;tag">&#60;/g:remoteLink&#62;</span></pre></div><p class="paragraph"/>The above code will execute the "showProgress()" function which may show a progress bar or whatever is appropriate. Other events include:
<ul class="star">
<li><code>onSuccess</code>  - The JavaScript function to call if successful</li>
<li><code>onFailure</code>  - The JavaScript function to call if the call failed</li>
<li><code>on_ERROR_CODE</code>  - The JavaScript function to call to handle specified error codes (eg on404="alert('not found!')")</li>
<li><code>onUninitialized</code>  - The JavaScript function to call the a Ajax engine failed to initialise</li>
<li><code>onLoading</code>  - The JavaScript function to call when the remote function is loading the response</li>
<li><code>onLoaded</code>  - The JavaScript function to call when the remote function is completed loading the response</li>
<li><code>onComplete</code>  - The JavaScript function to call when the remote function is complete, including any updates</li>
</ul><p class="paragraph"/>If you need a reference to the <code>XmlHttpRequest</code> object you can use the implicit event parameter <code>e</code> to obtain it:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:javascript&#62;</span>
    function fireMe(e) &#123;
        alert(<span class="xml&#45;quote">"XmlHttpRequest = "</span> + e)
    &#125;
&#125;
<span class="xml&#45;tag">&#60;/g:javascript&#62;</span>
<span class="xml&#45;tag">&#60;g:remoteLink action=<span class="xml&#45;quote">"example"</span>
              update=<span class="xml&#45;quote">"success"</span>
              onSuccess=<span class="xml&#45;quote">"fireMe(e)"</span>&#62;</span>Ajax Link<span class="xml&#45;tag">&#60;/g:remoteLink&#62;</span></pre></div>


<a name="6.7.2 Ajax with Prototype"><!-- Legacy link --></a>
<h2 id="ajaxWithPrototype">7.7.2 Ajax with Prototype</h2>
Grails features an external plugin to add <a href="http://www.prototypejs.org/" target="blank">Prototype</a> support to Grails. To install the plugin, list it in BuildConfig.groovy:<p class="paragraph"/><div class="code"><pre>runtime <span class="java&#45;quote">"&#58;prototype&#58;latest.release"</span></pre></div><p class="paragraph"/>This will download the current supported version of the Prototype plugin and install it into your Grails project. With that done you can add the following reference to the top of your page:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:javascript library=<span class="xml&#45;quote">"prototype"</span> /&#62;</span></pre></div><p class="paragraph"/>If you require <a href="http://script.aculo.us/" target="blank">Scriptaculous</a> too you can do the following instead:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:javascript library=<span class="xml&#45;quote">"scriptaculous"</span> /&#62;</span></pre></div><p class="paragraph"/>Now all of Grails tags such as <a href="../ref/Tags/remoteLink.html" class="tags">remoteLink</a>, <a href="../ref/Tags/formRemote.html" class="tags">formRemote</a> and <a href="../ref/Tags/submitToRemote.html" class="tags">submitToRemote</a> work with Prototype remoting.


<a name="6.7.3 Ajax with Dojo"><!-- Legacy link --></a>
<h2 id="ajaxWithDojo">7.7.3 Ajax with Dojo</h2>
Grails features an external plugin to add <a href="http://dojotoolkit.org/" target="blank">Dojo</a> support to Grails. To install the plugin, list it in BuildConfig.groovy:<p class="paragraph"/><div class="code"><pre>compile <span class="java&#45;quote">"&#58;dojo&#58;latest.release"</span></pre></div><p class="paragraph"/>This will download the current supported version of Dojo and install it into your Grails project. With that done you can add the following reference to the top of your page:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:javascript library=<span class="xml&#45;quote">"dojo"</span> /&#62;</span></pre></div><p class="paragraph"/>Now all of Grails tags such as <a href="../ref/Tags/remoteLink.html" class="tags">remoteLink</a>, <a href="../ref/Tags/formRemote.html" class="tags">formRemote</a> and <a href="../ref/Tags/submitToRemote.html" class="tags">submitToRemote</a> work with Dojo remoting.


<a name="6.7.4 Ajax with GWT"><!-- Legacy link --></a>
<h2 id="ajaxWithGWT">7.7.4 Ajax with GWT</h2>
Grails also features support for the <a href="http://code.google.com/webtoolkit/" target="blank">Google Web Toolkit</a> through a plugin. There is comprehensive <a href="http://grails.org/plugin/gwt" target="blank">documentation</a> available on the Grails wiki.


<a name="6.7.5 Ajax on the Server"><!-- Legacy link --></a>
<h2 id="ajaxOnTheServer">7.7.5 Ajax on the Server</h2>
There are a number of different ways to implement Ajax which are typically broken down into:
<ul class="star">
<li>Content Centric Ajax - Where you just use the HTML result of a remote call to update the page</li>
<li>Data Centric Ajax - Where you actually send an XML or JSON response from the server and programmatically update the page</li>
<li>Script Centric Ajax - Where the server sends down a stream of JavaScript to be evaluated on the fly</li>
</ul><p class="paragraph"/>Most of the examples in the <a href="../guide/single.html#ajax" class="guide">Ajax</a> section cover Content Centric Ajax where you are updating the page, but you may also want to use Data Centric or Script Centric. This guide covers the different styles of Ajax.<p class="paragraph"/><h4>Content Centric Ajax</h4><p class="paragraph"/>Just to re-cap, content centric Ajax involves sending some HTML back from the server and is typically done by rendering a template with the <a href="../ref/Controllers/render.html" class="controllers">render</a> method:<p class="paragraph"/><div class="code"><pre>def showBook() &#123;
    def b = Book.get(params.id)<p class="paragraph"/>    render(template: <span class="java&#45;quote">"bookTemplate"</span>, model: &#91;book: b&#93;)
&#125;</pre></div><p class="paragraph"/>Calling this on the client involves using the <a href="../ref/Tags/remoteLink.html" class="tags">remoteLink</a> tag:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:remoteLink action=<span class="xml&#45;quote">"showBook"</span> id=<span class="xml&#45;quote">"$&#123;book.id&#125;"</span>
              update=<span class="xml&#45;quote">"book$&#123;book.id&#125;"</span>&#62;</span>Update Book<span class="xml&#45;tag">&#60;/g:remoteLink&#62;</span><p class="paragraph"/><span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"book$&#123;book.id&#125;"</span>&#62;</span>
   <span class="xml&#45;comment">&#60;!&#45;&#45;existing book mark&#45;up &#45;&#45;&#62;</span>
<span class="xml&#45;tag">&#60;/div&#62;</span></pre></div><p class="paragraph"/><h4>Data Centric Ajax with JSON</h4><p class="paragraph"/>Data Centric Ajax typically involves evaluating the response on the client and updating programmatically. For a JSON response with Grails you would typically use Grails' <a href="../guide/single.html#xmlAndJSON" class="guide">JSON marshalling</a> capability:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">import</span> grails.converters.JSON<p class="paragraph"/>def showBook() &#123;
    def b = Book.get(params.id)<p class="paragraph"/>    render b as JSON
&#125;</pre></div><p class="paragraph"/>And then on the client parse the incoming JSON request using an Ajax event handler:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:javascript&#62;</span>
function updateBook(e) &#123;
    var book = eval(<span class="xml&#45;quote">"("</span>+e.responseText+<span class="xml&#45;quote">")"</span>) // evaluate the JSON
    $(<span class="xml&#45;quote">"book"</span> + book.id + <span class="xml&#45;quote">"_title"</span>).innerHTML = book.title
&#125;
<span class="xml&#45;tag">&#60;g:javascript&#62;</span>
<span class="xml&#45;tag">&#60;g:remoteLink action=<span class="xml&#45;quote">"test"</span> update=<span class="xml&#45;quote">"foo"</span> onSuccess=<span class="xml&#45;quote">"updateBook(e)"</span>&#62;</span>
    Update Book
<span class="xml&#45;tag">&#60;/g:remoteLink&#62;</span>
<span class="xml&#45;tag">&#60;g:set var=<span class="xml&#45;quote">"bookId"</span>&#62;</span>book$&#123;book.id&#125;<span class="xml&#45;tag">&#60;/g:set&#62;</span>
<span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"$&#123;bookId&#125;"</span>&#62;</span>
    <span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"$&#123;bookId&#125;_title"</span>&#62;</span>The Stand<span class="xml&#45;tag">&#60;/div&#62;</span>
<span class="xml&#45;tag">&#60;/div&#62;</span></pre></div><p class="paragraph"/><h4>Data Centric Ajax with XML</h4><p class="paragraph"/>On the server side using XML is equally simple:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">import</span> grails.converters.XML<p class="paragraph"/>def showBook() &#123;
    def b = Book.get(params.id)<p class="paragraph"/>    render b as XML
&#125;</pre></div><p class="paragraph"/>However, since DOM is involved the client gets more complicated:<p class="paragraph"/><div class="code"><pre><span class="xml&#45;tag">&#60;g:javascript&#62;</span>
function updateBook(e) &#123;
    var xml = e.responseXML
    var id = xml.getElementsByTagName(<span class="xml&#45;quote">"book"</span>).getAttribute(<span class="xml&#45;quote">"id"</span>)
    $(<span class="xml&#45;quote">"book"</span> + id + <span class="xml&#45;quote">"_title"</span>) = xml.getElementsByTagName(<span class="xml&#45;quote">"title"</span>)&#91;0&#93;.textContent
&#125;
<span class="xml&#45;tag">&#60;g:javascript&#62;</span>
<span class="xml&#45;tag">&#60;g:remoteLink action=<span class="xml&#45;quote">"test"</span> update=<span class="xml&#45;quote">"foo"</span> onSuccess=<span class="xml&#45;quote">"updateBook(e)"</span>&#62;</span>
    Update Book
<span class="xml&#45;tag">&#60;/g:remoteLink&#62;</span>
<span class="xml&#45;tag">&#60;g:set var=<span class="xml&#45;quote">"bookId"</span>&#62;</span>book$&#123;book.id&#125;<span class="xml&#45;tag">&#60;/g:set&#62;</span>
<span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"$&#123;bookId&#125;"</span>&#62;</span>
    <span class="xml&#45;tag">&#60;div id=<span class="xml&#45;quote">"$&#123;bookId&#125;_title"</span>&#62;</span>The Stand<span class="xml&#45;tag">&#60;/div&#62;</span>
<span class="xml&#45;tag">&#60;/div&#62;</span></pre></div><p class="paragraph"/><h4>Script Centric Ajax with JavaScript</h4><p class="paragraph"/>Script centric Ajax involves actually sending JavaScript back that gets evaluated on the client. An example of this can be seen below:<p class="paragraph"/><div class="code"><pre>def showBook() &#123;
    def b = Book.get(params.id)<p class="paragraph"/>    response.contentType = <span class="java&#45;quote">"text/javascript"</span>
    <span class="java&#45;object">String</span> title = b.title.encodeAsJavascript()
    render <span class="java&#45;quote">"&#36;('book$&#123;b.id&#125;_title')='$&#123;title&#125;'"</span>
&#125;</pre></div><p class="paragraph"/>The important thing to remember is to set the <code>contentType</code> to <code>text/javascript</code>. If you use Prototype on the client the returned JavaScript will automatically be evaluated due to this <code>contentType</code> setting.<p class="paragraph"/>Obviously in this case it is critical that you have an agreed client-side API as you don't want changes on the client breaking the server. This is one of the reasons Rails has something like RJS. Although Grails does not currently have a feature such as RJS there is a <a href="http://grails.org/plugin/dynamic-javascript" target="blank">Dynamic JavaScript Plugin</a> that offers similar capabilities.<p class="paragraph"/><h4>Responding to both Ajax and non-Ajax requests</h4><p class="paragraph"/>It's straightforward to have the same Grails controller action handle both Ajax and non-Ajax requests. Grails adds the <code>isXhr()</code> method to <code>HttpServletRequest</code> which can be used to identify Ajax requests. For example you could render a page fragment using a template for Ajax requests or the full page for regular HTTP requests:<p class="paragraph"/><div class="code"><pre>def listBooks() &#123;
    def books = Book.list(params)
    <span class="java&#45;keyword">if</span> (request.xhr) &#123;
        render template: <span class="java&#45;quote">"bookTable"</span>, model: &#91;books: books&#93;
    &#125; <span class="java&#45;keyword">else</span> &#123;
        render view: <span class="java&#45;quote">"list"</span>, model: &#91;books: books&#93;
    &#125;
&#125;</pre></div>


<a name="6.8 Content Negotiation"><!-- Legacy link --></a>
<h2 id="contentNegotiation">7.8 Content Negotiation</h2>
Grails has built in support for <a href="http://en.wikipedia.org/wiki/Content_negotiation" target="blank">Content negotiation</a> using either the HTTP <code>Accept</code> header, an explicit format request parameter or the extension of a mapped URI.<p class="paragraph"/><h4>Configuring Mime Types</h4><p class="paragraph"/>Before you can start dealing with content negotiation you need to tell Grails what content types you wish to support. By default Grails comes configured with a number of different content types within <code>grails-app/conf/Config.groovy</code> using the <code>grails.mime.types</code> setting:<p class="paragraph"/><div class="code"><pre>grails.mime.types = &#91; xml: &#91;'text/xml', 'application/xml'&#93;,
                      text: 'text&#45;plain',
                      js: 'text/javascript',
                      rss: 'application/rss+xml',
                      atom: 'application/atom+xml',
                      css: 'text/css',
                      csv: 'text/csv',
                      all: '&#42;/&#42;',
                      json: 'text/json',
                      html: &#91;'text/html','application/xhtml+xml'&#93;
                    &#93;</pre></div><p class="paragraph"/>The above bit of configuration allows Grails to detect to format of a request containing either the 'text/xml' or 'application/xml' media types as simply 'xml'. You can add your own types by simply adding new entries into the map.<p class="paragraph"/><h4>Content Negotiation using the format parameter</h4><p class="paragraph"/>Let's say a controller action can return a resource in a variety of formats: HTML, XML, and JSON. What format will the client get? The easiest and most reliable way for the client to control this is through a <code>format</code> URL parameter.<p class="paragraph"/>So if you, as a browser or some other client, want a resource as XML, you can use a URL like this:<p class="paragraph"/><div class="code"><pre>http://my.domain.org/books?format=xml</pre></div><p class="paragraph"/>The result of this on the server side is a <code>format</code> property on the <code>response</code> object with the value <code>xml</code> . You could code your controller action to return XML based on this property, but you can also make use of the controller-specific <code>withFormat()</code> method:<p class="paragraph"/><div class="code"><pre><span class="java&#45;keyword">import</span> grails.converters.JSON
<span class="java&#45;keyword">import</span> grails.converters.XML<p class="paragraph"/>class BookController &#123;<p class="paragraph"/>    def list() &#123;
        def books = Book.list()<p class="paragraph"/>        withFormat &#123;
            html bookList: books
            json &#123; render books as JSON &#125;
            xml &#123; render books as XML &#125;
        &#125;
    &#125;
&#125;</pre></div><p class="paragraph"/>In this example, Grails will only execute the block inside <code>withFormat()</code> that matches the requested content type. So if the preferred format is <code>html</code> then Grails will execute the <code>html()</code> call only. Each 'block' can either be a map model for the corresponding view (as we are doing for 'html' in the above example) or a closure. The closure can contain any standard action code, for example it can return a model or render content directly.<p class="paragraph"/>There is a special format, "all", that is handled differently from the explicit formats. If "all" is specified (normally this happens through the Accept header - see below), then the first block of <code>withFormat()</code> is executed. You should not add an explicit "all" block. In the above example, a format of "all" will trigger the <code>html</code> handler.<p class="paragraph"/><blockquote class="note">
When using <a href="../ref/Controllers/withFormat.html" class="controllers">withFormat</a> make sure it is the last call in your controller action as the return value of the <code>withFormat</code> method is used by the action to dictate what happens next.
</blockquote><p class="paragraph"/><h4>Using the Accept header</h4><p class="paragraph"/>Every incoming HTTP request has a special <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html" target="blank">Accept</a> header that defines what media types (or mime types) a client can "accept". In older browsers this is typically:<p class="paragraph"/><div class="code"><pre>&#42;/&#42;</pre></div><p class="paragraph"/>which simply means anything. However, newer browsers send more interesting values such as this one sent by Firefox 3:<p class="paragraph"/><div class="code"><pre>text/xml, application/xml, application/xhtml+xml, text/html;q=0.9, &#10;    text/plain;q=0.8, image/png, &#42;/&#42;;q=0.5</pre></div><p class="paragraph"/>This particular accept header is unhelpful because it indicates that XML is the preferred response format whereas the user is really expecting HTML. That's why Grails ignores the accept header by default. However, non-browser clients are typically more specific in their requirements and can send accept headers such as<p class="paragraph"/><div class="code"><pre>application/json</pre></div><p class="paragraph"/>If you want to support such clients and their accept headers, then simply add (or change) the <code>grails.mime.use.accept.header</code> setting in <code>Config.groovy</code> :<p class="paragraph"/><div class="code"><pre>grails.mime.use.accept.header = <span class="java&#45;keyword">true</span></pre></div><p class="paragraph"/>With this setting, Grails parses the incoming accept header and sets the appropriate value for the <code>format</code> response property. For example, if it sees the accept header above ('application/json') it will set <code>format</code> to <code>json</code> as you'd expect. And of course this works with the <code>withFormat()</code> method in just the same way as when the <code>format</code> URL parameter is set (although the URL parameter takes precedence).<p class="paragraph"/>An accept header of '&#42;/&#42;' results in a value of <code>all</code> for the <code>format</code> property.<p class="paragraph"/><blockquote class="note">
If you enable accept header parsing, it's usually best to handle XML and JSON responses in a different action from the HTML ones due to the problems with various browsers. You can then use <code>withFormat()</code> exclusively for the REST interface and avoid it for actions that render the normal HTML pages.
</blockquote><p class="paragraph"/><h4>Request format vs. Response format</h4><p class="paragraph"/>As of Grails 2.0, there is a separate notion of the  <em class="italic">request</em>  format and the  <em class="italic">response</em>  format. The request format is dictated by the <code>CONTENT_TYPE</code> header and is typically used to detect if the incoming request can be parsed into XML or JSON, whilst the response format uses the file extension, format parameter or ACCEPT header to attempt to deliver an appropriate response to the client.<p class="paragraph"/>The <a href="../ref/Controllers/withFormat.html" class="controllers">withFormat</a> available on controllers deals specifically with the response format. If you wish to add logic that deals with the request format then you can do so using a separate <code>withFormat</code> method available on the request:<p class="paragraph"/><div class="code"><pre>request.withFormat &#123;
    xml &#123;
        // read XML
    &#125;
    json &#123;
        // read JSON
    &#125;
&#125;</pre></div><p class="paragraph"/><h4>Content Negotiation with the format Request Parameter</h4><p class="paragraph"/>If fiddling with request headers if not your favorite activity you can override the format used by specifying a <code>format</code> request parameter:<p class="paragraph"/><div class="code"><pre>/book/list?format=xml</pre></div><p class="paragraph"/>You can also define this parameter in the <a href="../guide/single.html#urlmappings" class="guide">URL Mappings</a> definition:<p class="paragraph"/><div class="code"><pre><span class="java&#45;quote">"/book/list"</span>(controller:<span class="java&#45;quote">"book"</span>, action:<span class="java&#45;quote">"list"</span>) &#123;
    format = <span class="java&#45;quote">"xml"</span>
&#125;</pre></div><p class="paragraph"/><h4>Content Negotiation with URI Extensions</h4><p class="paragraph"/>Grails also supports content negotiation using URI extensions. For example given the following URI:<p class="paragraph"/><div class="code"><pre>/book/list.xml</pre></div><p class="paragraph"/>Grails will remove the extension and map it to <code>/book/list</code> instead whilst simultaneously setting the content format to <code>xml</code> based on this extension. This behaviour is enabled by default, so if you wish to turn it off, you must set the <code>grails.mime.file.extensions</code> property in <code>grails-app/conf/Config.groovy</code> to <code>false</code>:<p class="paragraph"/><div class="code"><pre>grails.mime.file.extensions = <span class="java&#45;keyword">false</span></pre></div><p class="paragraph"/><h4>Testing Content Negotiation</h4><p class="paragraph"/>To test content negotiation in a unit or integration test (see the section on <a href="../guide/single.html#testing" class="guide">Testing</a>) you can either manipulate the incoming request headers:<p class="paragraph"/><div class="code"><pre>void testJavascriptOutput() &#123;
    def controller = <span class="java&#45;keyword">new</span> TestController()
    controller.request.addHeader <span class="java&#45;quote">"Accept"</span>,
              <span class="java&#45;quote">"text/javascript, text/html, application/xml, text/xml, &#42;/&#42;"</span><p class="paragraph"/>    controller.testAction()
    assertEquals <span class="java&#45;quote">"alert('hello')"</span>, controller.response.contentAsString
&#125;</pre></div><p class="paragraph"/>Or you can set the format parameter to achieve a similar effect:<p class="paragraph"/><div class="code"><pre>void testJavascriptOutput() &#123;
    def controller = <span class="java&#45;keyword">new</span> TestController()
    controller.params.format = 'js'<p class="paragraph"/>    controller.testAction()
    assertEquals <span class="java&#45;quote">"alert('hello')"</span>, controller.response.contentAsString
&#125;</pre></div>



                <div style="clear:both;margin-top:15px;"></div>
                
                    <div class="toc-item prev-left"><a href="../guide/GORM.html">&lt;&lt; <strong>6</strong><span>Object Relational Mapping (GORM)</span></a></div>
                
                    <div class="toc-item next-right"><a href="../guide/validation.html"><strong>8</strong><span>Validation</span> >></a></div>
                
                <div style="clear:both"></div>
            </div>
        </td>
        <td id="col2">
            <div class="local clearfix">
                <div class="local-title">
                    <a href="../guide/index.html" target="mainFrame">Quick Reference</a>
                    <span class="toggle">(<a href="#" onclick="localToggle(); return false;">hide</a>)</span>
                </div>
                <div class="menu">
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Command Line</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Command%20Line/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/add-proxy.html">add-proxy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/alias.html">alias</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/bootstrap.html">bootstrap</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/bug-report.html">bug-report</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/clean.html">clean</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/clear-proxy.html">clear-proxy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/compile.html">compile</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/console.html">console</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-app.html">create-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-controller.html">create-controller</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-domain-class.html">create-domain-class</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-filters.html">create-filters</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-hibernate-cfg-xml.html">create-hibernate-cfg-xml</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-integration-test.html">create-integration-test</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-multi-project-build.html">create-multi-project-build</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-plugin.html">create-plugin</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-pom.html">create-pom</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-scaffold-controller.html">create-scaffold-controller</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-script.html">create-script</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-service.html">create-service</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-tag-lib.html">create-tag-lib</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/create-unit-test.html">create-unit-test</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/dependency-report.html">dependency-report</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/doc.html">doc</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/generate-all.html">generate-all</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/generate-controller.html">generate-controller</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/generate-views.html">generate-views</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/help.html">help</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/init.html">init</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/install-dependency.html">install-dependency</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/install-plugin.html">install-plugin</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/install-templates.html">install-templates</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/integrate-with.html">integrate-with</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/interactive.html">interactive</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/list-plugin-updates.html">list-plugin-updates</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/list-plugins.html">list-plugins</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/migrate-docs.html">migrate-docs</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/package-plugin.html">package-plugin</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/package.html">package</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/plugin-info.html">plugin-info</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/refresh-dependencies.html">refresh-dependencies</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/remove-proxy.html">remove-proxy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/run-app.html">run-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/run-script.html">run-script</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/run-war.html">run-war</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/schema-export.html">schema-export</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/set-proxy.html">set-proxy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/set-version.html">set-version</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/shell.html">shell</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/stats.html">stats</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/stop-app.html">stop-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/test-app.html">test-app</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/uninstall-plugin.html">uninstall-plugin</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/upgrade.html">upgrade</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/war.html">war</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Command%20Line/wrapper.html">wrapper</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Constraints</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Constraints/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Constraints/attributes.html">attributes</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/bindable.html">bindable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/blank.html">blank</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/creditCard.html">creditCard</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/email.html">email</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/inList.html">inList</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/matches.html">matches</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/max.html">max</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/maxSize.html">maxSize</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/min.html">min</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/minSize.html">minSize</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/notEqual.html">notEqual</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/nullable.html">nullable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/range.html">range</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/scale.html">scale</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/size.html">size</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/unique.html">unique</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/url.html">url</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/validator.html">validator</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Constraints/widget.html">widget</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Controllers</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Controllers/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Controllers/actionName.html">actionName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/afterInterceptor.html">afterInterceptor</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/allowedMethods.html">allowedMethods</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/beforeInterceptor.html">beforeInterceptor</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/bindData.html">bindData</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/chain.html">chain</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/controllerName.html">controllerName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/defaultAction.html">defaultAction</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/flash.html">flash</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/forward.html">forward</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/grailsApplication.html">grailsApplication</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/params.html">params</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/redirect.html">redirect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/render.html">render</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/request.html">request</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/response.html">response</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/servletContext.html">servletContext</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/session.html">session</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/withForm.html">withForm</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Controllers/withFormat.html">withFormat</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Database Mapping</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Database%20Mapping/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/autoImport.html">autoImport</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/autoTimestamp.html">autoTimestamp</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/batchSize.html">batchSize</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/cache.html">cache</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/cascade.html">cascade</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/column.html">column</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/comment.html">comment</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/discriminator.html">discriminator</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/dynamicInsert.html">dynamicInsert</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/dynamicUpdate.html">dynamicUpdate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/fetch.html">fetch</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/id.html">id</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/ignoreNotFound.html">ignoreNotFound</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/indexColumn.html">indexColumn</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/insertable.html">insertable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/joinTable.html">joinTable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/lazy.html">lazy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/order.html">order</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/sort.html">sort</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/table.html">table</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/type.html">type</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/updateable.html">updateable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Database%20Mapping/version.html">version</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Domain Classes</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Domain%20Classes/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/addTo.html">addTo</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/attach.html">attach</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/belongsTo.html">belongsTo</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/clearErrors.html">clearErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/constraints.html">constraints</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/count.html">count</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/countBy.html">countBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/createCriteria.html">createCriteria</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/delete.html">delete</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/discard.html">discard</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/embedded.html">embedded</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/errors.html">errors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/executeQuery.html">executeQuery</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/executeUpdate.html">executeUpdate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/exists.html">exists</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/fetchMode.html">fetchMode</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/find.html">find</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findAll.html">findAll</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findAllBy.html">findAllBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findAllWhere.html">findAllWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findBy.html">findBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findOrCreateBy.html">findOrCreateBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findOrCreateWhere.html">findOrCreateWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findOrSaveBy.html">findOrSaveBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findOrSaveWhere.html">findOrSaveWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/findWhere.html">findWhere</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/first.html">first</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/get.html">get</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/getAll.html">getAll</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/getDirtyPropertyNames.html">getDirtyPropertyNames</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/getPersistentValue.html">getPersistentValue</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/hasErrors.html">hasErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/hasMany.html">hasMany</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/hasOne.html">hasOne</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/ident.html">ident</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/instanceOf.html">instanceOf</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/isAttached.html">isAttached</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/isDirty.html">isDirty</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/last.html">last</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/list.html">list</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/listOrderBy.html">listOrderBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/load.html">load</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/lock.html">lock</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/mappedBy.html">mappedBy</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/mapping.html">mapping</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/merge.html">merge</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/namedQueries.html">namedQueries</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/properties.html">properties</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/read.html">read</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/refresh.html">refresh</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/removeFrom.html">removeFrom</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/save.html">save</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/transients.html">transients</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/validate.html">validate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/where.html">where</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/whereAny.html">whereAny</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/withCriteria.html">withCriteria</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/withNewSession.html">withNewSession</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/withSession.html">withSession</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Domain%20Classes/withTransaction.html">withTransaction</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Plug-ins</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Plug-ins/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/URL%20mappings.html">URL mappings</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/codecs.html">codecs</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/controllers.html">controllers</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/core.html">core</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/dataSource.html">dataSource</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/domainClasses.html">domainClasses</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/filters.html">filters</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/hibernate.html">hibernate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/i18n.html">i18n</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/logging.html">logging</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/scaffolding.html">scaffolding</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/services.html">services</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/servlets.html">servlets</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Plug-ins/web%20flow.html">web flow</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Services</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Services/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Services/scope.html">scope</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Services/transactional.html">transactional</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Servlet API</h1><div class="menu-sub">
                        
                            
                            <div class="menu-item"><a href="../ref/Servlet%20API/request.html">request</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Servlet%20API/response.html">response</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Servlet%20API/servletContext.html">servletContext</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Servlet%20API/session.html">session</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Tag Libraries</h1><div class="menu-sub">
                        
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/Usage.html">Usage</a></div>
                            
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/actionName.html">actionName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/controllerName.html">controllerName</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/flash.html">flash</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/pageScope.html">pageScope</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/params.html">params</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/request.html">request</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/response.html">response</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/servletContext.html">servletContext</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tag%20Libraries/session.html">session</a>
                            </div>
                            
                            </div>
                    </div>
                    
                    <div class="menu-block"><h1 class="menu-title" onclick="toggleRef(this.parentNode.childNodes[1])">Tags</h1><div class="menu-sub">
                        
                            
                            <div class="menu-item"><a href="../ref/Tags/actionSubmit.html">actionSubmit</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/actionSubmitImage.html">actionSubmitImage</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/applyLayout.html">applyLayout</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/checkBox.html">checkBox</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/collect.html">collect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/cookie.html">cookie</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/country.html">country</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/countrySelect.html">countrySelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/createLink.html">createLink</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/createLinkTo.html">createLinkTo</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/currencySelect.html">currencySelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/datePicker.html">datePicker</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/each.html">each</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/eachError.html">eachError</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/else.html">else</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/elseif.html">elseif</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/external.html">external</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/field.html">field</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/fieldValue.html">fieldValue</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/findAll.html">findAll</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/form.html">form</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/formRemote.html">formRemote</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/formatBoolean.html">formatBoolean</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/formatDate.html">formatDate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/formatNumber.html">formatNumber</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/grep.html">grep</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/hasErrors.html">hasErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/header.html">header</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/hiddenField.html">hiddenField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/if.html">if</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/img.html">img</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/include.html">include</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/isAvailable.html">isAvailable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/isNotAvailable.html">isNotAvailable</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/javascript.html">javascript</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/join.html">join</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/layoutBody.html">layoutBody</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/layoutHead.html">layoutHead</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/layoutTitle.html">layoutTitle</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/link.html">link</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/localeSelect.html">localeSelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/message.html">message</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/meta.html">meta</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/pageProperty.html">pageProperty</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/paginate.html">paginate</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/passwordField.html">passwordField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/radio.html">radio</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/radioGroup.html">radioGroup</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/remoteField.html">remoteField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/remoteFunction.html">remoteFunction</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/remoteLink.html">remoteLink</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/render.html">render</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/renderErrors.html">renderErrors</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/resource.html">resource</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/select.html">select</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/set.html">set</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/setProvider.html">setProvider</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/sortableColumn.html">sortableColumn</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/submitButton.html">submitButton</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/submitToRemote.html">submitToRemote</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/textArea.html">textArea</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/textField.html">textField</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/timeZoneSelect.html">timeZoneSelect</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/unless.html">unless</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/uploadForm.html">uploadForm</a>
                            </div>
                            
                            <div class="menu-item"><a href="../ref/Tags/while.html">while</a>
                            </div>
                            
                            </div>
                    </div>
                    
                </div>
            </div>
        </td>
    </tr>
</table>

<div id="footer">
    Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
    Sponsored by <a href="http://springsource.com">SpringSource</a>
</div>

<script type="text/javascript" src="../js/docs.js"></script>

</body>
</html>
